Implement REST API Backend for ACP Mobile App

[jeremyeder]

Implement REST API Backend for ACP Mobile App

Overview

The ACP Mobile companion app requires a REST API backend with real-time updates via Server-Sent Events (SSE). This issue tracks the implementation of the backend services needed to support the mobile application.

Documentation

• Requirements Document: docs/BACKEND_REQUIREMENTS.md
• OpenAPI Specification: specs/001-acp-mobile/contracts/acp-api.yaml
• Base URL (staging): https://ambient-code.apps.rosa.vteam-stage.7fpc.p3.openshiftapps.com/api/v1

Implementation Plan

Phase 1: Authentication (Week 1)

• Implement OAuth 2.0 + PKCE flow
• Integrate with Red Hat SSO
• Implement token refresh endpoint with automatic rotation
• Test token expiration and refresh mechanisms

Endpoints:

• POST /auth/login - Initiate OAuth flow, return authorization URL
• POST /auth/token - Exchange authorization code for JWT tokens
• POST /auth/refresh - Refresh access token using refresh token

Requirements:

• PKCE support for mobile security
• JWT tokens with configurable expiration (default: 1 hour)
• Automatic token rotation on refresh
• Red Hat SSO integration

Phase 2: Core APIs (Week 2)

• Implement Sessions CRUD operations
• Implement Repositories API
• Implement User Profile & Preferences
• Add comprehensive error handling and validation

Endpoints:

• GET/POST /sessions - List and create AI coding sessions
• GET/PATCH /sessions/{id} - Get and update session details
• GET /sessions/{id}/logs - Get session execution logs
• GET/POST/DELETE /repos - Manage connected repositories
• GET/PATCH /user/profile - User profile management
• GET/PATCH /user/preferences - User preferences (theme, notifications, quiet hours)

Data Models:

• Sessions: Track AI workflow execution with status, progress, and task history
• Repositories: User's connected GitHub repositories
• User preferences: Theme, notification settings, quiet hours configuration

Phase 3: Real-time Updates (Week 3)

• Implement SSE endpoint (GET /sse/sessions)
• Send session progress events (session.progress)
• Send session status transitions (session.status)
• Send session updates (session.updated)
• Test reconnection logic with exponential backoff

SSE Event Types:

1. session.progress - Incremental progress updates (don't trigger cache invalidation)
2. session.updated - Partial session changes (client merges into cache)
3. session.status - Status transitions (trigger notifications if awaiting_review)
4. notification.new - New GitHub notification (invalidates cache)
5. notification.read - Notification marked as read (invalidates cache)

Requirements:

• Persistent SSE connection with automatic reconnection
• Events update client cache without full API refetch
• Exponential backoff on reconnection (1s → 30s max)
• Connection management for mobile (disconnect on background, reconnect on foreground)

Phase 4: GitHub Integration (Week 4)

• Integrate GitHub API for notifications
• Implement Notifications API
• Add workflow suggestion logic (analyze notification type → suggest appropriate workflow)
• Test notification flow end-to-end

Endpoints:

• GET /notifications - List GitHub notifications with suggested workflows
• PATCH /notifications/{id} - Mark notification as read
• POST /notifications/{id}/mute - Mute notification thread

Workflow Suggestion Logic:

• Pull requests → review workflow
• Issues with "bug" label → bugfix workflow
• Feature requests → plan workflow
• General issues → research workflow

Phase 5: Polish & Production Readiness (Week 5)

• Implement push token registration (POST /user/push-token)
• Integrate Expo push notification service
• Add comprehensive request/response validation (Zod/similar)
• Security audit (SQL injection, XSS, auth bypass)
• Performance testing (response times, SSE scalability)
• Load testing with realistic mobile usage patterns

Technical Requirements

Security

• All endpoints require authentication (except /auth/*)
• OAuth 2.0 with PKCE for mobile security
• JWT tokens with Bearer authentication
• HTTPS only in production
• Input validation on all endpoints
• SQL injection and XSS prevention

Performance

• Response time: <2 seconds for most endpoints
• SSE: Streaming, indefinite connection support
• Efficient database queries with proper indexing
• Rate limiting on authenticated endpoints

Error Handling

• Standard error response format:

  {
    "error": "ErrorType",
    "message": "Human-readable message",
    "details": {}
  }

• Status codes: 200 (success), 201 (created), 204 (no content), 400 (bad request), 401 (unauthorized), 404 (not found), 500 (server error)
• 401 responses trigger automatic client token refresh (max 1 retry)

Third-party Integrations

1. Red Hat SSO - OAuth authentication provider
2. GitHub API - Fetch notifications, repository metadata
3. Expo Push Service - Send push notifications to mobile devices
4. Claude API - Chat feature (future implementation)

Development Support

Client Mock Data

The mobile client includes comprehensive mocks for development:

• Mock authentication (bypass OAuth)
• Mock sessions with realistic data and SSE events
• Mock GitHub notifications
• Environment variable toggles for selective mocking

Environment Variables

EXPO_PUBLIC_API_BASE_URL=https://ambient-code.apps.rosa.vteam-stage.7fpc.p3.openshiftapps.com/api/v1
EXPO_PUBLIC_OAUTH_DOMAIN=sso.redhat.com
EXPO_PUBLIC_OAUTH_CLIENT_ID=acp-mobile

Reference Implementation

• Client code: services/api/ (TypeScript API client)
• Type definitions: types/ (data models)
• Mock services: services/mock/ (expected behavior)

Acceptance Criteria

• All endpoints from OpenAPI spec implemented and tested
• OAuth 2.0 + PKCE authentication working with Red Hat SSO
• SSE connection stable with automatic reconnection
• GitHub notifications integration functional
• Push notifications working via Expo Push Service
• All endpoints validated with request/response schemas
• Security audit completed and issues addressed
• Performance testing shows <2s response times
• Production deployment successful on staging environment

Contact

For questions or clarification: Jeremy Eder (jeder@redhat.com)

---

Related: This backend will power the ACP Mobile companion app for AI-assisted development workflows. The client is built with React Native + Expo and uses React Query for data management.

[jeremyeder]

@claude rewrite the plan. Here is review feedback:

This issue is overshooting what I actually want for the first version of the mobile app.

My current goal for ACP Mobile is a basic companion app, not a full-blown, production-grade backend with all the bells and whistles. The spec here reads more like a “v2+ enterprise-ready backend” and I’d like to re-scope this issue so it’s realistic for a small implementation push.

Specific concerns:

• Scope creep: 5 phases, OAuth2 + PKCE with Red Hat SSO, SSE, GitHub notifications, workflow suggestion logic, Expo push, security + perf + load testing, etc. is a lot for what should be a simple companion app.
• MVP misalignment: For an initial dogfooding experience, I mostly need to read and lightly interact with ACP, not replicate the entire platform surface area.
• Cognitive load: The current issue body mixes requirements, architecture, implementation plan, and acceptance criteria. It’s hard to see the minimal “must-have” vs “nice-to-have later”.

What I actually want for MVP is closer to:

1. Keep auth simple (for now)

   • Start with a minimal auth story that’s good enough for internal/testing use:
     • e.g., reuse an existing ACP token or simple bearer token flow,
     • or even a short-lived “developer mode” auth approach.
   • Full OAuth2 + PKCE + Red Hat SSO integration can be a separate “Production Mobile Auth” follow-up.

2. Limit the API surface
   For a basic mobile experience, the backend only needs a small set of endpoints:

   • GET /sessions – list my sessions
   • GET /sessions/{id} – view a specific session
   • (Optional for MVP) GET /sessions/{id}/logs – view recent activity
   • (Optional) simple user preferences if/when the UI actually uses them

   Everything else (repos management, advanced preferences, notification workflows, etc.) can wait until the mobile app proves useful.

3. Defer real-time + notifications

   • Skip SSE and push notifications for MVP.
   • The client can start with polling (React Query refetch) and only move to SSE once we see a real need.
   • GitHub notifications + workflow suggestion logic can be spun out into a dedicated “Notifications v2” issue.

4. Right-size “Production Readiness”

   • For an early-stage companion app, we don’t need a formal “security audit + load testing” milestone in this issue.
   • We should of course follow sane defaults (HTTPS, basic input validation, no obvious footguns), but the heavy checklists can be future work once the app has real usage.

Proposal to simplify this issue:

• Rename/scope this issue to something like:
  “Implement Minimal REST API for ACP Mobile MVP”

• Trim the body down to:

  • short overview
  • minimal endpoint list for MVP
  • a small set of acceptance criteria focused on:
    • basic auth working
    • sessions list + detail working
    • mobile client can fetch and display data against staging

• Create follow-up issues for:

  • Full OAuth2 + PKCE with Red Hat SSO
  • SSE + real-time events
  • GitHub notifications + workflow suggestion engine
  • Push notifications (Expo)
  • Formal security/perf/load testing

That way, the backend work matches the modest initial goal for the mobile app, and this issue becomes something a single person can reasonably tackle without needing to boil the ocean.