Roadmap¶

Last audited: 2026-05-23

Legend¶

Symbol	Meaning
✅	Completed
🔄	In Progress
📋	Planned
🎯	High Priority
💡	Nice to Have

Phase 1: Bootstrap ✅¶

Core infrastructure, backend, and initial frontend shell.

Phase 1.1: Foundation ✅¶

Phase 1.2: Core Backend ✅¶

Phase 1.3: Frontend Shell 🔄¶

Phase 1.4: Production Readiness 🔄¶

Phase 1.5: Advanced Features 💡¶

Video session support
🔄 Custom reporting and analytics dashboard (navigation and placeholder screens exist)
🎯 🔄 Real-time session list updates via SSE (Hono streamSSE + Redis pub/sub; react-native-sse polyfill on native; coach/teacher session list refreshes instantly on peer mutations — no manual refresh)

Phase 2: Real Functionality 📋¶

Core product features that make the app usable end-to-end.

Phase 2.1: User Profile ✅¶

Phase 2.4: Invitations & Access ✅¶

🎯 Organization invite creation and resend from org user management
🎯 Role ceiling enforcement on invite creation (OrganizationAdmin all org roles, Manager coach/teacher only)
🎯 Invite token page supports immediate sign in when email already has account
🎯 Invite signup no longer auto-accepts; manual accept/decline required from pending invitations page
🎯 Pending invitations page with accept/decline actions and backend gate on protected routes until all invites are handled

Phase 2.2: Mentorships & 1:1 Calls ✅¶

Phase 2.3: File Library (Mentorships) ✅¶

Deduplication-aware file storage shared across mentorship objects (sessions, notes, etc.).

Phase 2.4: Mentorship Chat ✅¶

1:1 persistent chat for coach-teacher mentorships, delivered via SSE/Redis with Postgres persistence.

Phase 3: User Experience Improvements¶

Phase 3.1: Timezone Support ✅¶

Per-user and per-organization timezone configuration with immediate UI update.

Phase 3.2: Real-Time Presence & Badges ✅¶

🎯 Unread message badge on Messages tab — getChatUnreadCount aggregated across all active mentorships; badge updates via global SSE hook without requiring the Chat screen to be mounted
🎯 Global SSE hook (useGlobalSSE) — single persistent SSE connection shared across the app; dispatches chat-message events to invalidate unread counts and refresh chat lists regardless of which screen is active

Phase 3.3: Pull-to-Refresh & Retry ✅¶

Pull-to-refresh (RefreshControl) added to all screens with data queries: PlatformAdminUsersScreen, OrgAdminUsersScreen, PlatformAdminOrganizationsScreen, PendingInvitationsScreen, MentorshipDetailScreen, CoachSessionsScreen, UserBookingsScreen, MentorshipsScreen, MessagesScreen (FlatList), and ChatScreen (FlatList with isFetching && !isFetchingNextPage guard)
Retry button added to all error states so users can recover from transient network failures without leaving the screen

Phase 3.4: Chat Enhancements 🔄¶

Improvements to the existing 1:1 mentorship chat. Schema groundwork (editedAt, deletedAt) is already in place.

✅ File / image attachments — upload-first via /api/files (SHA-256 dedup); polymorphic file_attachments table links files to chat messages; presigned GET URLs returned on GET; inline image previews and doc links in ChatScreen
💡 Message edit — PATCH /api/mentorships/:id/chat/messages/:msgId endpoint (sender-only, within 15 minutes of sending; 422 after window); (edited) label in ChatBubble; long-press action menu in ChatScreen; chat-message-updated SSE event
💡 Message delete — DELETE /api/mentorships/:id/chat/messages/:msgId endpoint (sender-only or admin; soft-delete); tombstone "Message deleted" placeholder in ChatBubble; chat-message-deleted SSE event
💡 Message reactions — chat_reactions table + backend add/remove endpoints + SSE chat-reaction-added / chat-reaction-removed; reaction pills rendered below chat bubbles with toggle support
✅ Message threading / replies — replyToMessageId FK on chat_messages (migration 0013); enriched replyTo preview returned by API; long-press → Reply action in ChatScreen with quoted bubble and cancel bar
💡 Message search — full-text search on GET /api/mentorships/:id/chat/messages?q= using Postgres to_tsvector('simple', body) @@ plainto_tsquery(...); search toggle and query input added to ChatScreen header flow
💡 User presence (online/offline) — SSE heartbeat updates Redis user:{id}:lastSeen; new GET /api/users/:id/presence endpoint with org-safe ACL; online/offline status and dot rendered in chat header peer avatar

Phase 4: Offline-First Reliability 📋¶

Phase 4.1: Cache, Queue, and Sync 🎯¶

🎯 📋 Offline-first reliability and sync queue:
Device cache for core entities (sessions, mentorships, chat history, profile, organization context) with stale-while-revalidate behavior when reconnecting — via queryPersister.ts + PersistQueryClientProvider
Users can always view mentorship data, session data, chat history, and profile data from local cache while offline — TanStack Query cache persisted to AsyncStorage
Mutation outbox queue on native devices (iOS/Android) for offline actions (chat sends) with automatic retry on connectivity restore — outboxStore.ts + useOutbox.ts
Idempotent sync contract to avoid duplicates — stable clientMessageId used for outbox retries, backend already supports idempotency
Queue observability in native UI (pending/sent/failed states, manual retry for failed items) — OutboxStatusBar component in ChatScreen
Explicit online-only actions: session creation/rescheduling/cancellation and joining video calls require active connection and show clear offline error messaging — useOnlineAction hook applied in MentorshipDetailScreen, ScheduleSessionModal, VideoCallScreen
Connectivity guardrail: when offline, block online-only actions and keep queued chat messages persisted until successful ACK from backend on native — outbox auto-drains on reconnect
🐛 Fix OfflineBanner false-positive on Android — OfflineBanner is currently hidden because NetInfo reports isConnected: false on Android preview/emulator builds even with working connectivity. Tried: isInternetReachable removal, debounce (4s), HTTP probe (/api/health), grace-period + probe combo. Root cause: NetInfo fires isConnected: false at startup and the network stack is not ready when the probe runs. Needs a more reliable connectivity signal (e.g. NetInfo.fetch() polled after a longer delay, or a native module approach).

Phase 5: Design System Rollout ✅¶

Gradual, incremental implementation of DESIGN.md tokens and missing components across the codebase. Each sub-phase is independent and can be merged separately.

Phase 5.1: Token Infrastructure 🎯¶

🎯 Create frontend/src/lib/tokens.ts — typed TS constants for every design token: color map, spacing scale, border-radius scale, shadow definitions, and motion tokens (duration + easing); single source of truth for any code that cannot use a Tailwind class directly (e.g. StyleSheet, Animated values)
🎯 Extend frontend/tailwind.config.js theme — add brand color palette (blue/*, gray/*, bg-app, status colors), spacing aliases, border-radius keys, and shadow utilities matching DESIGN.md exactly; no raw hex values allowed outside this config file
📋 Document token usage convention in AGENTS.md / DESIGN.md — prefer Tailwind class over tokens.ts constant; use constant only when a class is impossible

Phase 5.2: Existing Component Audit ✅¶

🎯 Audit Button, Input Field, Card, Badge/Tag, Avatar against DESIGN.md tokens — replace all hardcoded hex colors and pixel values with Tailwind token classes or tokens.ts constants (Toast, ModalActionButtons, ModalContainer, StatCard, ScreenHeader, AppHeader, FormInput, RowActionsMenu)
📋 Enforce typography scale across key components — heading and body text classes migrated to brand-gray-* token classes; inline fontSize/fontWeight in Toast replaced with typography.body.md token
📋 Replace all inline shadowColor / elevation values with the canonical shadow/sm, shadow/md, shadow/lg tokens (Toast, RowActionsMenu, StatCard, ModalContainer)

Phase 5.3: Missing Components ✅¶

🎯 Nav Tab Bar — TabBadge component extracted; tab bar active/inactive colors migrated to colors.blue[500] / colors.gray[500] tokens in NativeNavigator
📋 Progress Bar — ProgressBar component (size: sm/md/lg × state: default/success/warning/error); animated fill via Animated.Value with duration.slow easing
💡 Toggle / Switch — Toggle component with 4 states (enabled-on/off, disabled-on/off); animated thumb + track with duration.fast easing
📋 Notification / Toast — Toast.tsx upgraded: supports optional title, message, variant, action button, and custom duration; fully backward-compatible with existing showToast('message') calls
💡 Icon system — lucide-react-native documented as the canonical icon library in DESIGN.md; standard sizes and token-based color usage defined; no ad-hoc icon imports from other libraries

Phase 5.4: Motion & Animation ✅¶

💡 Apply Fade In/Out pattern (200ms ease-out) to all Modal overlays — ModalContainer now animates backdrop (opacity 0→1 in 200ms) and card (translateY 320→0 in 300ms) independently; exit plays before unmount
💡 Apply Skeleton Shimmer loading state — SkeletonPlaceholder, SkeletonList, SkeletonListRow, SkeletonCard components added; replace ActivityIndicator on list screens with <SkeletonList />
💡 Apply Slide Up pattern (300ms ease-out) to bottom sheets and form drawers (deferred — no bottom-sheet component yet)
💡 Apply Scale + Fade (spring easing, 500ms) to any achievement / celebration UI introduced in future phases (deferred — no achievement UI yet)