# Makima Mobile Frontend Specification
**Version:** 1.0
**Date:** 2026-01-17
**Status:** Draft
**Contract Phase:** Specify
---
## Table of Contents
1. [Overview](#1-overview)
2. [Technical Specifications](#2-technical-specifications)
3. [Feature Specifications](#3-feature-specifications)
4. [UI/UX Specifications](#4-uiux-specifications)
5. [API Integration](#5-api-integration)
6. [Timeline and Resources](#6-timeline-and-resources)
7. [Appendices](#appendices)
---
## 1. Overview
### 1.1 Project Goals
The Makima mobile frontend enables developers to monitor and interact with AI-powered coding agents (Claude Code) from their mobile devices. The application addresses the critical need for real-time task monitoring, supervisor question responses, and push notifications when away from the desktop.
**Primary Goals:**
- Enable monitoring of running Claude Code tasks from mobile devices
- Provide instant push notifications for supervisor questions requiring user input
- Allow quick responses to AI agents without returning to desktop
- Support basic contract and task management on-the-go
**Success Criteria:**
| Metric | Target | Measurement |
|--------|--------|-------------|
| Push notification delivery | < 5 seconds | Time from question raised to device notification |
| Supervisor question response rate | > 80% | Questions answered via mobile vs ignored |
| App startup time | < 3 seconds | Cold start to usable dashboard |
| Task output streaming latency | < 1 second | Server-to-screen delay |
| Monthly active users | 30% of web users | Mobile users / total active users |
| App store rating | > 4.5 stars | iOS App Store and Google Play |
### 1.2 Target Platforms
| Platform | Minimum Version | Notes |
|----------|-----------------|-------|
| iOS | iOS 15.0+ | Required for modern notification features |
| Android | Android 8.0 (API 26)+ | Required for notification channels |
**Device Support:**
- iPhone 8 and newer
- iPad (universal app support planned for V2)
- Android phones with minimum 3GB RAM
- Tablets planned for V2 (adaptive layouts)
### 1.3 Technology Decision: React Native with Expo
**Chosen Approach:** React Native with Expo SDK
**Rationale:**
1. **Code Sharing** (Critical)
- Makima's web frontend is React 19 + TypeScript
- Can share: API client (`lib/api.ts`), TypeScript interfaces, WebSocket handlers
- Estimated 40-60% code reuse with web codebase
- React Native for Web enables future cross-platform component sharing
2. **Push Notifications** (Critical)
- Full native push notification support on iOS and Android
- Required for supervisor questions, task completion, merge conflicts
- Works in background (unlike PWA on iOS)
3. **Team Productivity**
- Zero ramp-up time - team already knows React + TypeScript
- Expo EAS simplifies build and deployment
- OTA updates for rapid iteration without app store review
4. **Real-time Features**
- Native WebSocket support for task output streaming
- Proven in chat applications with sub-100ms latency
- New Architecture (JSI) eliminates historical bridge bottleneck
5. **Long-term Sustainability**
- Mature 10+ year framework with strong community
- JavaScript developers abundant (20:1 vs Dart)
- Single team can maintain web + mobile
**Alternatives Considered:**
| Option | Reason Not Chosen |
|--------|-------------------|
| Flutter | Cannot share code with existing React/TypeScript codebase |
| PWA | iOS push notification limitations are a dealbreaker |
| Capacitor | WebView-based performance ceiling for real-time streaming |
---
## 2. Technical Specifications
### 2.1 Monorepo Structure
```
makima/
├── apps/
│ ├── web/ # Next.js/React web frontend (existing)
│ │ └── src/
│ │ ├── routes/
│ │ ├── components/
│ │ └── lib/
│ └── mobile/ # Expo/React Native app (new)
│ ├── app/ # Expo Router file-based routes
│ │ ├── (tabs)/ # Tab navigator screens
│ │ │ ├── index.tsx # Home/Dashboard
│ │ │ ├── contracts.tsx
│ │ │ ├── tasks.tsx
│ │ │ ├── files.tsx
│ │ │ └── settings.tsx
│ │ ├── contract/
│ │ │ └── [id].tsx # Contract detail
│ │ ├── task/
│ │ │ └── [id].tsx # Task detail with output
│ │ └── _layout.tsx # Root layout
│ ├── components/ # Mobile-specific components
│ ├── hooks/ # Mobile-specific hooks
│ ├── assets/ # Images, fonts
│ ├── app.json # Expo config
│ └── package.json
└── packages/
├── shared/ # Shared TypeScript interfaces
│ ├── types/
│ │ ├── api.ts # API response types
│ │ ├── contracts.ts # Contract types
│ │ ├── tasks.ts # Task/Mesh types
│ │ └── websocket.ts # WebSocket message types
│ └── utils/
│ ├── formatting.ts # Date, duration formatting
│ └── validation.ts # Input validation
├── api-client/ # Shared API client
│ ├── client.ts # Base fetch wrapper
│ ├── contracts.ts # Contract API functions
│ ├── tasks.ts # Task/Mesh API functions
│ ├── files.ts # File API functions
│ └── auth.ts # Authentication helpers
└── ui/ # Shared UI components (future)
└── components/
```
### 2.2 Shared Packages
#### 2.2.1 API Client (`packages/api-client/`)
Extract and refactor from `makima/frontend/src/lib/api.ts`:
```typescript
// packages/api-client/src/client.ts
export interface ApiConfig {
baseUrl: string;
wsBaseUrl: string;
getAuthToken: () => Promise<string | null>;
getApiKey: () => string | null;
}
export function createApiClient(config: ApiConfig) {
async function authFetch(url: string, options: RequestInit = {}): Promise<Response> {
const headers: HeadersInit = {
'Content-Type': 'application/json',
};
// Try JWT token first
const token = await config.getAuthToken();
if (token) {
headers['Authorization'] = `Bearer ${token}`;
} else {
// Fall back to API key
const apiKey = config.getApiKey();
if (apiKey) {
headers['X-Makima-API-Key'] = apiKey;
}
}
return fetch(`${config.baseUrl}${url}`, {
...options,
headers: { ...headers, ...options.headers },
});
}
return { authFetch };
}
```
**Key API Functions to Share:**
| Function | Description |
|----------|-------------|
| `listTasks()` | Get all tasks with status |
| `getTask(id)` | Get task details with subtasks |
| `startTask(id)` | Start a task |
| `stopTask(id)` | Stop a task |
| `sendTaskMessage(id, message)` | Send message to running task |
| `getTaskOutput(id)` | Get task output history |
| `listContracts()` | Get all contracts |
| `getContract(id)` | Get contract with relations |
| `changeContractPhase(id, phase)` | Change contract phase |
| `listPendingQuestions()` | Get supervisor questions |
| `answerQuestion(id, response)` | Answer a supervisor question |
#### 2.2.2 TypeScript Interfaces (`packages/shared/`)
Extract from `lib/api.ts` types section:
```typescript
// packages/shared/src/types/tasks.ts
export type TaskStatus =
| "pending"
| "initializing"
| "starting"
| "running"
| "paused"
| "blocked"
| "done"
| "failed"
| "merged";
export interface TaskSummary {
id: string;
contractId: string | null;
contractName: string | null;
name: string;
status: TaskStatus;
priority: number;
progressSummary: string | null;
isSupervisor: boolean;
createdAt: string;
updatedAt: string;
}
// packages/shared/src/types/contracts.ts
export type ContractPhase = "research" | "specify" | "plan" | "execute" | "review";
export type ContractStatus = "active" | "completed" | "archived";
export interface ContractSummary {
id: string;
name: string;
description: string | null;
phase: ContractPhase;
status: ContractStatus;
fileCount: number;
taskCount: number;
createdAt: string;
}
```
#### 2.2.3 WebSocket Handlers (`packages/api-client/`)
```typescript
// packages/api-client/src/websocket.ts
export interface TaskSubscriptionMessage {
type: 'task_status' | 'task_output' | 'supervisor_question';
taskId: string;
data: unknown;
}
export function createTaskSubscription(
wsBaseUrl: string,
authToken: string,
onMessage: (msg: TaskSubscriptionMessage) => void,
onError: (error: Error) => void
): WebSocket {
const ws = new WebSocket(`${wsBaseUrl}/api/v1/mesh/tasks/subscribe`);
ws.onopen = () => {
ws.send(JSON.stringify({ type: 'auth', token: authToken }));
};
ws.onmessage = (event) => {
const message = JSON.parse(event.data) as TaskSubscriptionMessage;
onMessage(message);
};
ws.onerror = (event) => {
onError(new Error('WebSocket error'));
};
return ws;
}
```
### 2.3 Authentication Flow
#### 2.3.1 Supabase Integration
```
┌─────────────────────────────────────────────────────────────┐
│ Authentication Flow │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────┐ ┌──────────┐ ┌────────┐ ┌─────────┐ │
│ │ User │───▶│ Login │───▶│Supabase│───▶│ JWT │ │
│ │ │ │ Screen │ │ Auth │ │ Token │ │
│ └─────────┘ └──────────┘ └────────┘ └────┬────┘ │
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │ Secure │ │
│ │ Storage │ │
│ │(Keychain)│ │
│ └────┬─────┘ │
│ │ │
│ ┌───────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────┐ ┌──────────┐ ┌────────┐ │
│ │ API │◀───│ Auth │◀───│ Token │ │
│ │ Request │ │ Header │ │Refresh │ │
│ └─────────┘ └──────────┘ └────────┘ │
│ │
└───────────────────────────────────────────────────────────┘
```
**Implementation:**
```typescript
// apps/mobile/src/lib/auth.ts
import * as SecureStore from 'expo-secure-store';
import { createClient } from '@supabase/supabase-js';
const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY, {
auth: {
storage: {
getItem: (key) => SecureStore.getItemAsync(key),
setItem: (key, value) => SecureStore.setItemAsync(key, value),
removeItem: (key) => SecureStore.deleteItemAsync(key),
},
autoRefreshToken: true,
persistSession: true,
},
});
export async function signIn(email: string, password: string) {
const { data, error } = await supabase.auth.signInWithPassword({
email,
password,
});
if (error) throw error;
return data;
}
export async function getSession() {
const { data: { session } } = await supabase.auth.getSession();
return session;
}
```
**Biometric Authentication (V2):**
- Face ID / Touch ID for quick app unlock
- Stored session remains valid, biometric just unlocks UI
- Falls back to password if biometric fails
### 2.4 Push Notification Architecture
```
┌────────────────────────────────────────────────────────────────┐
│ Push Notification Architecture │
├────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌────────────┐ │
│ │ Makima │ │ Mobile │ │
│ │ Backend │ │ App │ │
│ │ (Rust) │ │ (Expo) │ │
│ └────┬─────┘ └──────┬─────┘ │
│ │ │ │
│ │ 1. Event occurs │ │
│ │ (supervisor question, │ │
│ │ task complete, etc) │ │
│ │ │ │
│ ▼ │ │
│ ┌────────────┐ │ │
│ │Notification│ 2. Push via FCM/APNs │ │
│ │ Service │────────────────────────────────▶ │ │
│ │ │ │ │
│ └────────────┘ │ │
│ │ │ │
│ │ 3. Store push token │ │
│ │◀────────────────────────────────────────────│ │
│ │ │ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Notification Categories │ │
│ ├─────────────────────────────────────────────────────────┤ │
│ │ Category │ Priority │ Actions │ │
│ ├───────────────────┼──────────┼──────────────────────────┤ │
│ │ SUPERVISOR_QN │ High │ Quick reply, View │ │
│ │ TASK_COMPLETE │ Medium │ View output │ │
│ │ TASK_FAILED │ Medium │ View error, Retry │ │
│ │ MERGE_CONFLICT │ High │ View conflict │ │
│ │ CONTRACT_UPDATE │ Low │ View contract │ │
│ └───────────────────┴──────────┴──────────────────────────┘ │
└────────────────────────────────────────────────────────────────┘
```
**Expo Push Notifications Setup:**
```typescript
// apps/mobile/src/lib/notifications.ts
import * as Notifications from 'expo-notifications';
import * as Device from 'expo-device';
import { Platform } from 'react-native';
export async function registerForPushNotifications() {
if (!Device.isDevice) {
return null; // Push doesn't work in simulator
}
const { status: existingStatus } = await Notifications.getPermissionsAsync();
let finalStatus = existingStatus;
if (existingStatus !== 'granted') {
const { status } = await Notifications.requestPermissionsAsync();
finalStatus = status;
}
if (finalStatus !== 'granted') {
return null;
}
const token = await Notifications.getExpoPushTokenAsync({
projectId: 'your-project-id',
});
// Register token with backend
await registerPushToken(token.data);
return token.data;
}
// Configure notification channels (Android)
if (Platform.OS === 'android') {
Notifications.setNotificationChannelAsync('supervisor-questions', {
name: 'Supervisor Questions',
importance: Notifications.AndroidImportance.HIGH,
vibrationPattern: [0, 250, 250, 250],
});
Notifications.setNotificationChannelAsync('task-updates', {
name: 'Task Updates',
importance: Notifications.AndroidImportance.DEFAULT,
});
}
```
**Backend Integration Required:**
```rust
// New endpoint needed: POST /api/v1/users/me/push-token
#[derive(Deserialize)]
struct RegisterPushTokenRequest {
token: String,
platform: String, // "ios" | "android"
}
// New table needed: push_tokens
// - id: UUID
// - user_id: UUID (FK to users)
// - token: String
// - platform: String
// - created_at: Timestamp
// - last_used_at: Timestamp
```
---
## 3. Feature Specifications
### 3.1 MVP (Phase 1) - 4-6 Weeks
#### 3.1.1 Task Monitoring
**User Stories:**
- As a developer, I want to see all my running tasks so I can monitor their progress
- As a developer, I want to view real-time task output so I can follow what Claude is doing
- As a developer, I want to see task completion/failure status so I know when work is done
**Screens:**
1. **Task List Screen**
- List all tasks with status indicators
- Filter by status (running, pending, done, failed)
- Sort by updated time
- Pull-to-refresh
2. **Task Detail Screen**
- Task name, status, progress summary
- Real-time output streaming (WebSocket)
- Elapsed time and turn count
- Start/Stop controls
- Send message input
**Acceptance Criteria:**
- [ ] Task list loads within 2 seconds
- [ ] Real-time output updates within 1 second of server event
- [ ] WebSocket reconnects automatically on network change
- [ ] Offline state shows cached task list with "offline" indicator
- [ ] Start/stop operations provide haptic feedback
#### 3.1.2 Push Notifications
**User Stories:**
- As a developer, I want push notifications for supervisor questions so I can respond quickly
- As a developer, I want notifications when tasks complete or fail so I stay informed
- As a developer, I want to configure which notifications I receive
**Notification Types:**
| Type | Priority | Payload Example |
|------|----------|-----------------|
| Supervisor Question | High | `{ taskId, question, choices[], context }` |
| Task Completed | Medium | `{ taskId, taskName, duration }` |
| Task Failed | Medium | `{ taskId, taskName, errorMessage }` |
| Merge Conflict | High | `{ taskId, conflictFiles[] }` |
**Acceptance Criteria:**
- [ ] Push notifications arrive within 5 seconds of event
- [ ] Tapping notification navigates to relevant screen
- [ ] Notification preferences persist across app restarts
- [ ] Silent/vibration mode respected
#### 3.1.3 Supervisor Question Responses
**User Stories:**
- As a developer, I want to answer supervisor questions from my phone so tasks aren't blocked
- As a developer, I want quick-reply buttons for common responses
- As a developer, I want to see question context before answering
**Flow:**
```
Push Notification
↓
[View Full Question] or [Quick Reply Option]
↓
Question Detail Screen (if View)
├── Question text
├── Context (truncated with "expand")
├── Choice buttons
└── Custom text input
↓
Submit Answer → Loading → Success Toast → Return to Dashboard
```
**Acceptance Criteria:**
- [ ] Quick reply from notification completes in < 3 seconds
- [ ] Full question context viewable with expand/collapse
- [ ] Answer submission shows loading state
- [ ] Success/failure feedback via toast
- [ ] Answered questions disappear from pending list
### 3.2 V1 (Phase 2) - 4-6 Weeks
#### 3.2.1 Full Task Control
**Additional Features:**
- Create new tasks (simplified form)
- Edit task plan/description
- Delete tasks
- Reassign failed tasks to new daemon
- View task checkpoints
#### 3.2.2 Contract Management
**Screens:**
1. **Contract List Screen**
- List contracts with phase badges
- Filter by phase and status
- Contract progress indicators
2. **Contract Detail Screen**
- Phase stepper visualization
- Associated files list
- Associated tasks list
- Phase transition controls
- Chat history viewer
**Acceptance Criteria:**
- [ ] Contract list shows phase progression
- [ ] Phase change requires confirmation
- [ ] Linked files and tasks navigable
#### 3.2.3 Offline Viewing
**Cached Data:**
- Last 20 contracts
- Last 50 tasks
- Task output (last 1000 lines per task)
- User preferences
**Sync Strategy:**
- Background sync on app foreground
- Optimistic UI updates with server reconciliation
- Conflict resolution: server wins for task state
### 3.3 V2 (Phase 3) - 2-4 Weeks
#### 3.3.1 Home Screen Widgets
**iOS Widgets (WidgetKit):**
- **Small Widget**: Running task count + attention badge
- **Medium Widget**: Top 3 active tasks with status
- **Large Widget**: Dashboard summary
**Android Widgets:**
- Similar functionality using React Native's widget support
- Glance-able active task status
#### 3.3.2 Biometric Authentication
- Face ID / Touch ID for app unlock
- Optional: require biometric for sensitive operations
- Graceful fallback to password
#### 3.3.3 Tablet Layouts
**iPad / Android Tablet:**
- Split view: list on left, detail on right
- Floating panels for modals
- Landscape-optimized layouts
- Multi-window support
---
## 4. UI/UX Specifications
### 4.1 Navigation Structure
```
┌─────────────────────────────────────────────────────────────┐
│ Navigation Structure │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Status Bar │ │
│ ├─────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ │ │
│ │ │ │
│ │ Main Content │ │
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │
│ ├─────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │ │
│ │ │ Home │ │Tasks │ │Mesh │ │Files │ │More │ │ │
│ │ │ 🏠 │ │ 📋 │ │ 🤖 │ │ 📁 │ │ ⚙️ │ │ │
│ │ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ │ │
│ │ Bottom Tab Navigation │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
Tab Details:
─────────────────────────────────────────────────────────────
│ Tab │ Primary Screen │ Badge │
├──────────┼─────────────────────┼────────────────────┤
│ Home │ Dashboard │ Attention count │
│ Tasks │ Contract List │ Active task count │
│ Mesh │ Task/Agent List │ Running count │
│ Files │ File List │ None │
│ More │ Settings │ Update available │
─────────────────────────────────────────────────────────────
```
### 4.2 Core Screens with Wireframes
#### 4.2.1 Dashboard/Home Screen
```
┌─────────────────────────────────────────┐
│ Good morning, Alex 🔔 (3) │ ← Header with notification badge
├─────────────────────────────────────────┤
│ │
│ ⚠️ 2 items need attention │ ← Attention banner (tappable)
│ ┌─────────────────────────────────────┐ │
│ │ 🤔 Supervisor Question │ │
│ │ Task: Auth System Refactor │ │
│ │ "Which auth method should I use?" │ │
│ │ ┌────────┐ ┌────────┐ ┌────────┐ │ │
│ │ │ OAuth │ │ JWT │ │ More │ │ │ ← Quick action buttons
│ │ └────────┘ └────────┘ └────────┘ │ │
│ └─────────────────────────────────────┘ │
├─────────────────────────────────────────┤
│ Active Tasks See All │
│ ┌─────────────────────────────────────┐ │
│ │ 🟢 Auth System Refactor │ │
│ │ ●●●●●●●○○○ 70% • 23 min │ │ ← Progress bar and time
│ │ Writing OAuth handler... │ │ ← Progress summary
│ └─────────────────────────────────────┘ │
│ ┌─────────────────────────────────────┐ │
│ │ 🟡 Mobile API Endpoints Paused │ │
│ │ ●●●●○○○○○○ 40% │ │
│ └─────────────────────────────────────┘ │
├─────────────────────────────────────────┤
│ Recent Activity │
│ ┌─────────────────────────────────────┐ │
│ │ ✅ Task "DB Migration" done 5m │ │
│ │ 📝 Contract "Mobile" → specify 15m │ │
│ │ ❌ Task "Tests" failed 1h │ │
│ └─────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────┘
```
#### 4.2.2 Task List Screen
```
┌─────────────────────────────────────────┐
│ Tasks [🔍] [Filter] │
├─────────────────────────────────────────┤
│ ┌─────────────────────────────────────┐ │
│ │ Running (2) │ │ ← Collapsible section
│ │ ├───────────────────────────────────┤ │
│ │ │ 🟢 Auth System Refactor │ │
│ │ │ Mobile Version • 23 min • 70% │ │
│ │ ├───────────────────────────────────┤ │
│ │ │ 🟢 API Documentation │ │
│ │ │ API Docs Contract • 8 min • 30% │ │
│ └─────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────┐ │
│ │ Pending (3) │ │
│ │ ├───────────────────────────────────┤ │
│ │ │ ⏳ Database Migrations │ │
│ │ │ Backend Contract • Queued │ │
│ │ ├───────────────────────────────────┤ │
│ │ │ ⏳ Test Suite Updates │ │
│ │ │ Backend Contract • Queued │ │
│ └─────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────┐ │
│ │ Completed Today (5) │ │
│ │ ├───────────────────────────────────┤ │
│ │ │ ✅ Config Refactor 12:30 PM │ │
│ │ │ ✅ Bug Fix #234 11:15 AM │ │
│ └─────────────────────────────────────┘ │
│ │
│ ┌─────────────┐ │
│ │ + New │ │ ← FAB for new task (V1)
│ └─────────────┘ │
└─────────────────────────────────────────┘
```
#### 4.2.3 Task Detail Screen
```
┌─────────────────────────────────────────┐
│ ← Auth System Refactor │
├─────────────────────────────────────────┤
│ │
│ Status: 🟢 Running • 23 min elapsed │
│ ●●●●●●●○○○ 70% • 47 turns │
│ │
│ Contract: Mobile Version │
│ Branch: feature/auth-oauth │
│ │
├─────────────────────────────────────────┤
│ ┌───────┐ ┌───────┐ ┌───────┐ │
│ │ Stop │ │Restart│ │Message│ │ ← Action buttons
│ │ ⏹️ │ │ 🔄 │ │ 💬 │ │
│ └───────┘ └───────┘ └───────┘ │
├─────────────────────────────────────────┤
│ Live Output [⇕ Full] │
├─────────────────────────────────────────┤
│ │ Reading src/auth/provider.ts... │
│ │ │
│ │ Found OAuth implementation at L45 │
│ │ │
│ │ Edit: src/auth/config.ts │
│ │ + export const AUTH_PROVIDERS = { │
│ │ + google: { ... }, │
│ │ + github: { ... } │
│ │ + } │
│ │ │
│ │ Running tests... │
│ │ ▌ │ ← Live cursor
│ │
├─────────────────────────────────────────┤
│ ┌─────────────────────────────────┐ ⬆️ │
│ │ Send a message to the agent... │ │
│ └─────────────────────────────────┘ │
└─────────────────────────────────────────┘
```
#### 4.2.4 Supervisor Question Screen
```
┌─────────────────────────────────────────┐
│ ← Supervisor Question │
├─────────────────────────────────────────┤
│ │
│ Task: Auth System Refactor │
│ Contract: Mobile Version │
│ Asked 2 minutes ago │
│ │
├─────────────────────────────────────────┤
│ │
│ 🤔 Question │
│ ───────────────────────────────────── │
│ Which authentication method should │
│ I implement for the mobile API? │
│ │
├─────────────────────────────────────────┤
│ │
│ 📋 Context [Expand] │
│ ───────────────────────────────────── │
│ The API currently uses session-based │
│ auth. Mobile apps typically need... │
│ │
├─────────────────────────────────────────┤
│ │
│ Choose an option: │
│ │
│ ┌─────────────────────────────────┐ │
│ │ OAuth 2.0 │ │
│ │ Industry standard, supports │ │
│ │ Google, GitHub, etc. │ │
│ └─────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────┐ │
│ │ JWT Tokens │ │
│ │ Stateless, good for mobile │ │
│ └─────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────┐ │
│ │ API Keys │ │
│ │ Simple, good for internal use │ │
│ └─────────────────────────────────┘ │
│ │
│ Or write a custom response: │
│ ┌─────────────────────────────────┐ │
│ │ │ │
│ │ │ │
│ └─────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────┐ │
│ │ Submit Answer │ │
│ └─────────────────────────────────┘ │
│ │
└─────────────────────────────────────────┘
```
### 4.3 Touch Targets and Accessibility
#### 4.3.1 Minimum Touch Target Sizes
| Element Type | Minimum Size | Recommended Size |
|--------------|--------------|------------------|
| Primary buttons | 44×44pt | 48×48pt |
| Icon buttons | 44×44pt | 44×44pt |
| List item height | 44pt | 56-72pt |
| Input fields | 44pt height | 48pt height |
| Tab bar items | 44×44pt | 49×49pt (iOS standard) |
| Spacing between tappable elements | 8pt | 12pt |
#### 4.3.2 Accessibility Features
**VoiceOver / TalkBack Support:**
- All interactive elements have accessibility labels
- Task status announced with context ("Auth task, running, 70% complete")
- Supervisor questions announced with urgency
**Reduced Motion:**
- Respect system preference `prefers-reduced-motion`
- Disable animations when enabled
- Instant transitions instead of animated
**Dynamic Type:**
- Support iOS Dynamic Type scaling
- Support Android font scaling
- Test with 200% scale
**Color Contrast:**
- All text meets WCAG 2.1 AA (4.5:1 minimum)
- Status indicators have text labels, not color alone
### 4.4 Color System
```
┌─────────────────────────────────────────────────────────────┐
│ Color System │
├─────────────────────────────────────────────────────────────┤
│ │
│ Brand │
│ ┌──────────┐ │
│ │ Primary │ #6366F1 (Indigo) │
│ │ │ Actions, links, active states │
│ └──────────┘ │
│ │
│ Semantic │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Success │ │ Warning │ │ Error │ │ Info │ │
│ │ #22C55E │ │ #F59E0B │ │ #EF4444 │ │ #3B82F6 │ │
│ │ Green │ │ Amber │ │ Red │ │ Blue │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ Task Status Colors │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Running │ │ Pending │ │ Done │ │ Failed │ │
│ │ #22C55E │ │ #F59E0B │ │ #6366F1 │ │ #EF4444 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ Neutral (Slate) │
│ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │
│ │ 50 │ │ 100 │ │ 200 │ │ 500 │ │ 800 │ │ 900 │ │
│ │F8FAFC│ │F1F5F9│ │E2E8F0│ │64748B│ │1E293B│ │0F172A│ │
│ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ │
│ │
│ Dark Mode │
│ ┌────────────────────────────────────────────────────┐ │
│ │ Background: #0F172A (Slate 900) │ │
│ │ Surface: #1E293B (Slate 800) │ │
│ │ Text: #F1F5F9 (Slate 100) │ │
│ └────────────────────────────────────────────────────┘ │
│ │
│ Light Mode │
│ ┌────────────────────────────────────────────────────┐ │
│ │ Background: #F8FAFC (Slate 50) │ │
│ │ Surface: #FFFFFF (White) │ │
│ │ Text: #1E293B (Slate 800) │ │
│ └────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
```
### 4.5 Typography
```
┌─────────────────────────────────────────────────────────────┐
│ Typography │
├─────────────────────────────────────────────────────────────┤
│ │
│ Font Families │
│ ───────────────────────────────────────────────────────── │
│ Display/Headings: Inter (600-700 weight) │
│ Fallback: SF Pro Display (iOS) │
│ Roboto (Android) │
│ │
│ Body: Inter (400-500 weight) │
│ Fallback: SF Pro Text (iOS) │
│ Roboto (Android) │
│ │
│ Monospace: JetBrains Mono │
│ Fallback: SF Mono (iOS) │
│ Roboto Mono (Android) │
│ │
│ Type Scale │
│ ───────────────────────────────────────────────────────── │
│ │ Name │ Size │ Weight │ Line Height │ Use Case │
│ ├────────────┼───────┼────────┼─────────────┼─────────────│
│ │ Display │ 28pt │ 700 │ 36pt │ Page titles │
│ │ Title │ 22pt │ 600 │ 28pt │ Section │
│ │ Headline │ 18pt │ 600 │ 24pt │ Card titles │
│ │ Body │ 16pt │ 400 │ 24pt │ Main text │
│ │ Callout │ 15pt │ 500 │ 20pt │ Emphasis │
│ │ Caption │ 14pt │ 400 │ 18pt │ Secondary │
│ │ Micro │ 12pt │ 400 │ 16pt │ Timestamps │
│ │ Code │ 14pt │ 400 │ 20pt │ Output │
│ │
└─────────────────────────────────────────────────────────────┘
```
---
## 5. API Integration
### 5.1 Endpoints Required for Mobile
#### 5.1.1 Core Endpoints (Existing)
| Endpoint | Method | Mobile Usage |
|----------|--------|--------------|
| `/api/v1/mesh/tasks` | GET | Task list |
| `/api/v1/mesh/tasks/{id}` | GET | Task detail |
| `/api/v1/mesh/tasks/{id}/start` | POST | Start task |
| `/api/v1/mesh/tasks/{id}/stop` | POST | Stop task |
| `/api/v1/mesh/tasks/{id}/message` | POST | Send message |
| `/api/v1/mesh/tasks/{id}/output` | GET | Fetch output history |
| `/api/v1/contracts` | GET | Contract list |
| `/api/v1/contracts/{id}` | GET | Contract detail |
| `/api/v1/contracts/{id}/phase` | POST | Change phase |
| `/api/v1/mesh/questions` | GET | Pending questions |
| `/api/v1/mesh/questions/{id}/answer` | POST | Answer question |
| `/api/v1/files` | GET | File list |
| `/api/v1/files/{id}` | GET | File detail |
#### 5.1.2 New Endpoints Required
| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/api/v1/users/me/push-token` | POST | Register push notification token |
| `/api/v1/users/me/push-token` | DELETE | Unregister push token |
| `/api/v1/users/me/notification-preferences` | GET, PUT | Notification settings |
| `/api/v1/mobile/dashboard` | GET | Optimized dashboard data |
**Dashboard Endpoint Response:**
```typescript
interface DashboardResponse {
attentionItems: AttentionItem[];
activeTasks: TaskSummary[];
recentActivity: ActivityItem[];
stats: {
runningTasks: number;
pendingTasks: number;
completedToday: number;
pendingQuestions: number;
};
}
```
### 5.2 WebSocket Subscriptions
#### 5.2.1 Task Subscription
**Endpoint:** `wss://api.makima.jp/api/v1/mesh/tasks/subscribe`
**Message Types:**
```typescript
// Incoming messages
interface TaskStatusMessage {
type: 'task_status';
taskId: string;
status: TaskStatus;
progressSummary: string | null;
}
interface TaskOutputMessage {
type: 'task_output';
taskId: string;
messageType: string;
content: string;
toolName?: string;
createdAt: string;
}
interface SupervisorQuestionMessage {
type: 'supervisor_question';
questionId: string;
taskId: string;
contractId: string;
question: string;
choices: string[];
context: string | null;
}
```
**Mobile-Specific Considerations:**
- Reconnect with exponential backoff on network change
- Queue messages while reconnecting
- Request full state on reconnect (fetch missed output)
### 5.3 Push Notification Backend Requirements
#### 5.3.1 Database Schema
```sql
-- Push notification tokens
CREATE TABLE push_tokens (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
token TEXT NOT NULL,
platform VARCHAR(10) NOT NULL, -- 'ios' | 'android' | 'expo'
device_id VARCHAR(255),
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
last_used_at TIMESTAMP WITH TIME ZONE,
UNIQUE(user_id, token)
);
-- Notification preferences
CREATE TABLE notification_preferences (
user_id UUID PRIMARY KEY REFERENCES users(id) ON DELETE CASCADE,
supervisor_questions BOOLEAN DEFAULT true,
task_completions BOOLEAN DEFAULT true,
task_failures BOOLEAN DEFAULT true,
merge_conflicts BOOLEAN DEFAULT true,
contract_updates BOOLEAN DEFAULT false,
quiet_hours_start TIME,
quiet_hours_end TIME,
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
```
#### 5.3.2 Push Service Integration
**Recommended: Expo Push Notification Service**
```rust
// Backend integration with Expo Push API
async fn send_push_notification(
tokens: Vec<String>,
title: String,
body: String,
data: serde_json::Value,
category: NotificationCategory,
) -> Result<(), PushError> {
let messages: Vec<ExpoPushMessage> = tokens.iter().map(|token| {
ExpoPushMessage {
to: token.clone(),
title: title.clone(),
body: body.clone(),
data: data.clone(),
sound: "default",
priority: category.priority(),
channel_id: category.android_channel(),
category_id: category.ios_category(),
}
}).collect();
let client = reqwest::Client::new();
client.post("https://exp.host/--/api/v2/push/send")
.json(&messages)
.send()
.await?;
Ok(())
}
```
---
## 6. Timeline and Resources
### 6.1 Phase 1: MVP - 4-6 Weeks
**Goal:** Basic task monitoring and supervisor question responses
| Week | Deliverables |
|------|--------------|
| 1 | Project setup, monorepo structure, shared packages extraction |
| 2 | Authentication flow, API client integration |
| 3 | Task list, task detail screens with real-time output |
| 4 | Push notifications setup, supervisor question flow |
| 5 | Polish, bug fixes, internal testing |
| 6 | Beta testing, App Store/Play Store submission |
**Resources:**
- 1 mobile developer (full-time)
- 0.5 backend developer (push notification infrastructure)
- 0.25 designer (design review)
**Risks:**
| Risk | Mitigation |
|------|------------|
| Push notification delivery issues | Test early with Expo push tools |
| WebSocket reliability on mobile | Implement robust reconnection logic |
| App Store review delays | Submit early, prepare for feedback |
### 6.2 Phase 2: V1 - 4-6 Weeks
**Goal:** Full task and contract management
| Week | Deliverables |
|------|--------------|
| 1-2 | Contract list and detail screens |
| 2-3 | Task creation and editing |
| 3-4 | Offline caching with SQLite |
| 4-5 | File viewing (read-only) |
| 5-6 | Polish, testing, release |
**Resources:**
- 1 mobile developer (full-time)
- 0.25 backend developer (API optimizations)
### 6.3 Phase 3: Polish - 2-4 Weeks
**Goal:** Premium experience with widgets and biometrics
| Week | Deliverables |
|------|--------------|
| 1 | iOS widgets (WidgetKit) |
| 2 | Android widgets |
| 3 | Biometric authentication |
| 4 | Tablet layouts, performance optimization |
**Resources:**
- 1 mobile developer (full-time)
### 6.4 Total Timeline Summary
```
┌─────────────────────────────────────────────────────────────┐
│ Development Timeline │
├─────────────────────────────────────────────────────────────┤
│ │
│ Phase 1: MVP │
│ ├─────────────────────────────────┤ │
│ Week 1 Week 4 Week 6 │
│ │ │ │ │
│ Setup ────▶ Core ────▶ Polish ────▶ Release │
│ │
│ Phase 2: V1 │
│ ├─────────────────────────────┤ │
│ Week 7 Week 10 Week 12 │
│ │ │ │ │
│ Contracts ──▶ Offline ──▶ Release │
│ │
│ Phase 3: Polish │
│ ├─────────────┤ │
│ Week 13 Week 16 │
│ │ │ │
│ Widgets ─▶ Release │
│ │
│ Total: 14-16 weeks to full feature set │
│ │
└─────────────────────────────────────────────────────────────┘
```
---
## Appendices
### Appendix A: Expo Configuration
```json
// app.json
{
"expo": {
"name": "Makima",
"slug": "makima-mobile",
"version": "1.0.0",
"orientation": "portrait",
"icon": "./assets/icon.png",
"userInterfaceStyle": "automatic",
"splash": {
"image": "./assets/splash.png",
"resizeMode": "contain",
"backgroundColor": "#0F172A"
},
"ios": {
"supportsTablet": true,
"bundleIdentifier": "jp.makima.mobile",
"infoPlist": {
"NSFaceIDUsageDescription": "Use Face ID to unlock Makima"
}
},
"android": {
"adaptiveIcon": {
"foregroundImage": "./assets/adaptive-icon.png",
"backgroundColor": "#0F172A"
},
"package": "jp.makima.mobile"
},
"plugins": [
"expo-router",
"expo-secure-store",
[
"expo-notifications",
{
"icon": "./assets/notification-icon.png",
"color": "#6366F1"
}
]
]
}
}
```
### Appendix B: Dependencies
```json
// package.json (apps/mobile)
{
"dependencies": {
"expo": "~50.0.0",
"expo-router": "~3.4.0",
"expo-secure-store": "~12.8.0",
"expo-notifications": "~0.27.0",
"expo-device": "~5.9.0",
"expo-local-authentication": "~13.8.0",
"@supabase/supabase-js": "^2.90.0",
"react": "18.2.0",
"react-native": "0.73.0",
"react-native-safe-area-context": "4.8.0",
"@react-navigation/native": "^6.0.0",
"@react-navigation/bottom-tabs": "^6.0.0",
"react-native-reanimated": "~3.6.0",
"react-native-gesture-handler": "~2.14.0",
"@tanstack/react-query": "^5.0.0",
"zustand": "^4.5.0"
},
"devDependencies": {
"@types/react": "~18.2.0",
"typescript": "^5.3.0",
"jest": "^29.0.0",
"@testing-library/react-native": "^12.0.0"
}
}
```
### Appendix C: State Management
```typescript
// apps/mobile/src/stores/taskStore.ts
import { create } from 'zustand';
import { persist, createJSONStorage } from 'zustand/middleware';
import AsyncStorage from '@react-native-async-storage/async-storage';
interface TaskState {
tasks: TaskSummary[];
selectedTaskId: string | null;
taskOutputs: Record<string, TaskOutputEntry[]>;
// Actions
setTasks: (tasks: TaskSummary[]) => void;
updateTask: (taskId: string, update: Partial<TaskSummary>) => void;
appendOutput: (taskId: string, output: TaskOutputEntry) => void;
selectTask: (taskId: string | null) => void;
}
export const useTaskStore = create<TaskState>()(
persist(
(set) => ({
tasks: [],
selectedTaskId: null,
taskOutputs: {},
setTasks: (tasks) => set({ tasks }),
updateTask: (taskId, update) => set((state) => ({
tasks: state.tasks.map((t) =>
t.id === taskId ? { ...t, ...update } : t
),
})),
appendOutput: (taskId, output) => set((state) => ({
taskOutputs: {
...state.taskOutputs,
[taskId]: [...(state.taskOutputs[taskId] || []), output].slice(-1000),
},
})),
selectTask: (taskId) => set({ selectedTaskId: taskId }),
}),
{
name: 'makima-tasks',
storage: createJSONStorage(() => AsyncStorage),
partialize: (state) => ({
tasks: state.tasks.slice(0, 50), // Cache last 50 tasks
}),
}
)
);
```
### Appendix D: Testing Strategy
**Unit Tests:**
- Shared package functions (API client, utilities)
- State management logic (Zustand stores)
- Component rendering (React Native Testing Library)
**Integration Tests:**
- API client with mock server
- WebSocket message handling
- Authentication flow
**E2E Tests (Detox):**
- Login flow
- Task list navigation
- Supervisor question response
- Push notification handling
**Manual Testing Checklist:**
- [ ] App launches in < 3 seconds
- [ ] Task list shows real-time updates
- [ ] Push notifications arrive promptly
- [ ] Supervisor questions can be answered
- [ ] App handles network changes gracefully
- [ ] Dark mode works correctly
- [ ] VoiceOver/TalkBack navigable
---
*Document generated for Makima Mobile Frontend contract - Specify phase*
*Last updated: 2026-01-17*
