Mobile App

Overview

This example demonstrates using Omni Architect for a native mobile application with iOS and Android platform-specific considerations, gesture-based navigation, and offline-first architecture.

Use Case

We’re building a fitness tracking mobile app with:

Native iOS and Android apps
Offline workout logging
Real-time sync when online
Apple Health / Google Fit integration
Gesture-based navigation patterns

The PRD

prd-fitness-app.md

# PRD: FitTrack Mobile App

## Feature: Workout Logging

### User Stories
1. As a **gym member**, I want to **log my workout offline**,
   so that I can **track progress without internet**.

2. As a **fitness enthusiast**, I want to **sync my Apple Health data**,
   so that I can **see all my activity in one place**.

3. As a **mobile user**, I want to **use swipe gestures to navigate**,
   so that I can **quickly switch between exercises**.

### Mobile-Specific Requirements
- Native iOS (SwiftUI) and Android (Jetpack Compose)
- Offline-first with SQLite local storage
- Background sync with conflict resolution
- Haptic feedback on key actions
- Platform-specific navigation (tab bar vs bottom nav)

### Acceptance Criteria
- [ ] Workout logged in < 10 seconds
- [ ] Offline mode with automatic sync
- [ ] Apple Health HealthKit integration
- [ ] Google Fit API integration
- [ ] Swipe left/right for exercise navigation
- [ ] Pull-to-refresh for sync

### Entities
| Entity | Attributes |
|--------|------------|
| User | id, name, email, platform, health_kit_enabled |
| Workout | id, user_id, date, duration, sync_status |
| Exercise | id, workout_id, name, sets, reps, weight |
| HealthData | id, user_id, source, data_type, value, recorded_at |

### State Management
- Local: Not synced (📱)
- Syncing: In progress (🔄)
- Synced: Confirmed (✓)
- Conflict: Needs resolution (⚠️)

Running for Mobile

Configure with Apple HIG design system

For iOS-first design:

.omni-architect-ios.yml

project_name: "FitTrack iOS"
design_system: "apple-hig"
locale: "en-US"
validation_threshold: 0.88

diagram_types:
  - flowchart
  - sequence
  - stateDiagram
  - journey

design_tokens:
  colors:
    primary: "#007AFF"
    secondary: "#5856D6"
    success: "#34C759"
    error: "#FF3B30"
  typography:
    font_family: "SF Pro"
    heading_size: 34
    body_size: 17
  spacing:
    base: 8
    scale: 2

Run with mobile-specific diagrams

skills run omni-architect \
  --prd_source "./docs/prd-fitness-app.md" \
  --figma_file_key "mobile123XYZ" \
  --figma_access_token "$FIGMA_TOKEN" \
  --config ".omni-architect-ios.yml"

Review mobile-optimized flows

The pipeline generates mobile-specific patterns:

Gesture-based navigation flows
State management for offline/online
Platform-specific interaction sequences

Generated Diagrams

Flowchart: Workout Logging Flow

State Diagram: Sync Status

Sequence: Apple Health Integration

Journey: First-Time User

Validation Report

{
  "overall_score": 0.89,
  "status": "approved",
  "breakdown": {
    "coverage": {
      "score": 0.92,
      "details": "All 3 user stories covered + offline/online scenarios"
    },
    "consistency": {
      "score": 0.88,
      "details": "Sync state consistent across diagrams"
    },
    "completeness": {
      "score": 0.85,
      "details": "Offline, online, conflict, and error paths covered"
    },
    "traceability": {
      "score": 0.91,
      "details": "Mobile-specific requirements mapped to flows"
    },
    "naming_coherence": {
      "score": 0.90,
      "details": "Consistent state naming (Local, Syncing, Synced, Conflict)"
    },
    "dependency_integrity": {
      "score": 0.93,
      "details": "Workout → Exercise hierarchy clear"
    }
  },
  "warnings": [
    "Consider adding error recovery sequence for HealthKit failures"
  ],
  "suggestions": [
    "Add push notification flow for sync completion",
    "Document haptic feedback patterns in interaction specs",
    "Add Android-specific Google Fit integration sequence"
  ]
}

Figma Structure

📁 FitTrack iOS - Omni Architect
├── 📄 Index
├── 📄 User Flows
│   ├── 🖼️ Workout Logging Flow
│   ├── 🖼️ Offline Mode Flow
│   └── 🖼️ Platform Navigation (iOS vs Android)
├── 📄 State Machines
│   ├── 🖼️ Sync Status Lifecycle
│   └── 🖼️ Workout Session States
├── 📄 User Journeys
│   ├── 🖼️ First Workout Experience
│   └── 🖼️ Offline to Online Journey
├── 📄 Integration Specs
│   ├── 🖼️ Apple HealthKit Sequence
│   └── 🖼️ Background Sync Process
└── 📄 Component Library
    ├── 🧩 iOS HIG Tokens (SF Pro, iOS colors)
    ├── 🧩 Gesture Indicators
    └── ���� Sync Status Icons

Mobile-Specific Features

Gesture-Based Navigation

Flowcharts include swipe gestures (left/right) for mobile UX patterns.

Offline-First Architecture

State diagrams model complex offline/online sync states and conflict resolution.

Platform-Specific Design

Apple HIG design system for iOS, Material Design for Android variants.

Native Integrations

Sequence diagrams for HealthKit and Google Fit API flows.

Design System Comparison

iOS (Apple HIG)
Android (Material Design)

design_system: "apple-hig"
design_tokens:
  colors:
    primary: "#007AFF"
    secondary: "#5856D6"
    success: "#34C759"
    error: "#FF3B30"
  typography:
    font_family: "SF Pro"
    heading_size: 34
    body_size: 17
  spacing:
    base: 8
    scale: 2

Tab bar navigation
Native iOS haptics
HealthKit integration
SF Symbols icons

design_system: "material-3"
design_tokens:
  colors:
    primary: "#6750A4"
    secondary: "#625B71"
    success: "#00897B"
    error: "#BA1A1A"
  typography:
    font_family: "Roboto"
    heading_size: 28
    body_size: 16
  spacing:
    base: 8
    scale: 1.5

Bottom navigation
Material haptics
Google Fit integration
Material Icons

Key Learnings

State Diagrams for Sync Logic

Mobile apps with offline capabilities require clear state management. The state diagram revealed 4 distinct states (Local, Syncing, Synced, Conflict) that we initially missed in the PRD.

Platform-Specific Flows

Generate separate Figma files for iOS and Android with platform-specific design systems (apple-hig vs material-3) to maintain native patterns.

Gesture Documentation

Include gesture annotations (swipe left/right, pull-to-refresh) directly in flowcharts for clear handoff to developers.

Integration Sequences

HealthKit and Google Fit integrations are complex. Sequence diagrams caught missing permission flows and data type mappings early.

Performance Metrics

Metric	iOS	Android
Validation Score	0.89	0.87
Diagrams Generated	5	5
Time to Figma	48s	51s
Platform Accuracy	96%	94%
Coverage	92%	90%

Platform accuracy measures how well the generated Figma assets match platform-specific HIG guidelines.

Code Example: Using Hooks

Automate mobile-specific validations:

.omni-architect.yml

hooks:
  on_validation_approved: |
    # Generate platform-specific specs
    npm run generate:ios-specs
    npm run generate:android-specs
  
  on_figma_complete: |
    # Notify mobile team on Slack
    curl -X POST $SLACK_WEBHOOK \
      -d '{"text": "New mobile designs ready in Figma!"}'
  
  on_error: |
    # Alert on validation failures
    npm run alert:mobile-team

See Custom Workflows for more hook examples.

Next Steps

Custom Workflows

Add hooks for mobile CI/CD

Design Systems

Deep dive on Apple HIG vs Material

State Diagrams

Master sync state modeling

CI/CD Integration

Automate mobile design pipeline

Use Cases

Advanced

Overview

Use Case

The PRD

Running for Mobile

Generated Diagrams

Flowchart: Workout Logging Flow

State Diagram: Sync Status

Sequence: Apple Health Integration

Journey: First-Time User

Flowchart: Platform-Specific Navigation

Validation Report

Figma Structure

Mobile-Specific Features

Gesture-Based Navigation

Offline-First Architecture

Platform-Specific Design

Native Integrations

Design System Comparison

Key Learnings

Performance Metrics

Code Example: Using Hooks

Next Steps

Custom Workflows

Design Systems

State Diagrams

CI/CD Integration

Build docs developers (and LLMs) love

Use Cases

Advanced

​Overview

​Use Case

​The PRD

​Running for Mobile

​Generated Diagrams

​Flowchart: Workout Logging Flow

​State Diagram: Sync Status

​Sequence: Apple Health Integration

​Journey: First-Time User

​Flowchart: Platform-Specific Navigation

​Validation Report

​Figma Structure

​Mobile-Specific Features

Gesture-Based Navigation

Offline-First Architecture

Platform-Specific Design

Native Integrations

​Design System Comparison

​Key Learnings

​Performance Metrics

​Code Example: Using Hooks

​Next Steps

Custom Workflows

Design Systems

State Diagrams

CI/CD Integration

Build docs developers (and LLMs) love

Overview

Use Case

The PRD

Running for Mobile

Generated Diagrams

Flowchart: Workout Logging Flow

State Diagram: Sync Status

Sequence: Apple Health Integration

Journey: First-Time User

Flowchart: Platform-Specific Navigation

Validation Report

Figma Structure

Mobile-Specific Features

Design System Comparison

Key Learnings

Performance Metrics

Code Example: Using Hooks

Next Steps