ACP Mobile - MVP

Mobile companion app for the Ambient Code Platform (ACP).

Features (MVP - Phase 1-3 + Real-time Updates)

✅ User Story 1: Monitor Active AI Sessions

• View dashboard with active sessions
• See session status, progress, and model information
• Navigate to detailed session view
• Real-time progress updates via Server-Sent Events (SSE)
• Error indicators for failed sessions
• Offline support with cached data
• Connection status indicator with retry capability

Tech Stack

• Framework: React Native 0.81.5 + Expo SDK 54
• Language: TypeScript 5.x
• Routing: Expo Router (file-based)
• State Management: React Context + TanStack Query
• Storage: Expo SecureStore + AsyncStorage
• Auth: OAuth 2.0 + PKCE (prepared for Red Hat SSO)
• Performance: Comprehensive monitoring suite (dev only)

Performance Monitoring

The app includes comprehensive performance monitoring in development mode:

• 📊 Visual Dashboard - Tap the 📊 button for real-time metrics
• 💾 Memory Tracking - Detect memory leaks and high usage
• 🎬 FPS Monitoring - Track frame rate and UI jank
• 🔄 Render Tracking - Identify unnecessary re-renders
• 📈 React Query DevTools - Monitor cache and network activity

Quick Access:

// In development console
performance.report() // Full performance report

See Performance Monitoring Guide for complete documentation.

Quick Start

npm install && npm start

Run on device:

• iOS: npm run ios
• Android: npm run android
• Physical device: Scan QR code with Expo Go app

See Setup Guide for detailed installation instructions.

Development Mode

The app currently uses mock data for testing without a backend:

• Mock sessions are defined in utils/mockData.ts
• Mock SSE events are generated by MockSSEService in utils/mockData.ts
• To switch to real API:
  • Set USE_MOCK_DATA = false in hooks/useSessions.ts
  • Set USE_MOCK_SSE = false in hooks/useRealtimeSession.ts
• API configuration is in utils/constants.ts

Mock SSE Behavior:

• Generates random session update events every 10-15 seconds
• 60% progress updates, 25% session updates, 15% status changes
• Only affects running sessions
• Simulates realistic real-time update patterns

Project Structure

app/                    # Expo Router screens
├── (tabs)/
│   └── index.tsx      # Dashboard
├── sessions/
│   ├── [id].tsx       # Session detail
│   └── index.tsx      # Sessions list
└── _layout.tsx        # Root layout with providers

components/            # Reusable components
├── session/          # Session-specific components
├── ui/               # Base UI components
└── layout/           # Layout components

services/             # Business logic
├── api/             # API clients
├── auth/            # Authentication
└── storage/         # Data persistence

hooks/               # Custom React hooks
types/               # TypeScript types
utils/               # Utilities and constants

Documentation

📚 Comprehensive documentation is available at the documentation site (deployed automatically)

Quick Links

• Getting Started

  • Quick Start - Get running in 5 minutes
  • Setup Guide - Complete development environment setup
  • Troubleshooting - Common issues and solutions

• Architecture & Design

  • Architecture Overview - Platform architecture and integration
  • Design System - UI/UX guidelines, colors, typography

• Development

  • Contributing Guide - How to contribute
  • API Reference - TypeScript API documentation
  • Changelog - Version history

• Project Management

  • Development Backlog - Upcoming features and improvements
  • Security Audit - Security assessment and recommendations

Serve Documentation Locally

# Install Python dependencies
pip install -r requirements-docs.txt

# Start documentation server
mkdocs serve

# Visit http://localhost:8000

MVP Implementation Status

✅ Phase 1: Setup & Infrastructure (11 tasks)

• Project initialization
• Dependencies installed
• TypeScript configured
• Directory structure created

✅ Phase 2: Foundational Infrastructure (14 tasks)

• TypeScript type definitions
• OAuth PKCE authentication flow
• API client with token refresh
• AsyncStorage cache utilities
• Theme system (light/dark/system)
• Auth and Theme contexts

✅ Phase 3: User Story 1 - Monitor Sessions (12 tasks)

• Sessions API service
• useSessions hook with polling (replaced with SSE)
• useOffline hook
• SessionCard, SessionProgress, ModelBadge, StatusBadge components
• Header with greeting and refresh spinner
• Dashboard screen
• Session detail screen
• Sessions list screen with filters

✅ Phase 4: Real-time Updates (Event-Driven Architecture)

• Server-Sent Events (SSE) implementation
• Event type definitions (types/realtime.ts)
• RealtimeService with automatic reconnection and exponential backoff
• MockSSEService for development testing
• useRealtimeSession hook for SSE integration
• Direct React Query cache updates (no refetches)
• Connection state UI with retry functionality
• Support for session.progress, session.updated, and session.status events

Testing the MVP

1. Start the app: npm start
2. Open on device: Scan QR code or run in simulator
3. View dashboard: See mock active sessions with real-time updates
4. Watch live updates: Session progress bars update every 10-15 seconds automatically
5. Tap session: View detailed session information
6. View all sessions: Use "View All" or "{N} Running" button
7. Filter sessions: Use filter chips (All/Running/Paused/Done)
8. Pull to refresh: Test manual refresh functionality
9. Connection status: If mock SSE disabled, see connection state indicator
10. Test reconnection: When error state, tap "Retry" button

Next Steps

The following features are planned:

• Phase 5: User Story 2 - Review Completed Work
• Phase 6: User Story 3 - GitHub Notifications
• Phase 7: User Story 4 - Interactive Chat
• Phase 8: User Story 5 - Create New Sessions
• Phase 9: User Story 6 - Settings & Preferences

Backend Integration

To connect to the real ACP backend:

1. Update API_BASE_URL in utils/constants.ts
2. Configure OAuth client ID and redirect URI
3. Set USE_MOCK_DATA = false in hooks/useSessions.ts
4. Set USE_MOCK_SSE = false in hooks/useRealtimeSession.ts
5. Ensure backend endpoints match services/api/*.ts
6. Implement SSE endpoint at ${API_BASE_URL}/sse/sessions with event types:
   • session.progress - Progress updates
   • session.updated - Incremental session changes
   • session.status - Status transitions

Troubleshooting

App won't start:

npx expo start -c  # Clear cache

Type errors:

npm run lint  # Check for issues

Can't find module errors:

npm install  # Reinstall dependencies

Contributing

This is an MVP implementation. See specs/001-acp-mobile/ for full specifications, planning documents, and task breakdown.

License

Internal Red Hat project.