Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
314 lines (238 loc) · 10.3 KB

ARCHITECTURE.md

File metadata and controls

314 lines (238 loc) · 10.3 KB

Architecture

This document describes the architecture of the Jules Mobile Client application.

Overview

┌─────────────────────────────────────────────────────────────────┐
│                        App Entry Point                          │
│                         app/_layout.tsx                         │
├─────────────────────────────────────────────────────────────────┤
│                          Providers                              │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │  ApiKeyProvider │  │   I18nProvider  │  │  ThemeProvider  │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│                       Expo Router                               │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                    Stack Navigator                       │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐  │   │
│  │  │ (tabs)      │  │create-session│  │ session/[id]   │  │   │
│  │  │ Tab Nav     │  │   Modal      │  │    Screen      │  │   │
│  │  └─────────────┘  └─────────────┘  └─────────────────┘  │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

Layer Architecture

1. Presentation Layer (Screens)

Located in app/ directory, using Expo Router's file-based routing.

Screen Path Description
Sessions List /(tabs)/index.tsx Main session list with FAB
Settings /(tabs)/settings.tsx API key and preferences
Session Detail /session/[id].tsx Chat view with activities
Create Session /create-session.tsx New task creation modal

2. Component Layer

Jules Components (components/jules/)

Specialized components for Jules functionality:

  • ActivityItem - Renders different activity types (messages, plans, artifacts)
  • ActivityItemSkeleton - Chat-style shimmer skeleton for loading states
  • SessionCard - Session list item with i18n status badge
  • SessionCardSkeleton - Card shimmer skeleton for loading states
  • LoadingOverlay - Full-screen loading indicator (legacy)
  • DataRenderer - Generic JSON/data renderer
  • CodeBlock - Syntax highlighted code display

GitHub Components (components/github/)

Components for GitHub integration features:

  • EnhancedRepositoryManager - Advanced repository browsing and management
  • GithubSessionCreator - Session creation wizard with GitHub context
  • GithubUrlHandler - URL parsing and deep linking for GitHub URLs
  • NotificationsCenter - Centralized notification management interface
  • OptimizedWorkflowDashboard - Performance-optimized workflow monitoring
  • PullRequestAnalyzer - AI-powered pull request analysis and review
  • RepositorySyncManager - Background synchronization and conflict resolution
  • WebhookManagement - Webhook configuration and event handling
  • WorkflowCard, WorkflowDashboard, WorkflowJobCard - Workflow visualization components
  • WorkflowRunCard, WorkflowRunDetails, WorkflowLogsViewer - Workflow execution details
  • WorkflowNotifications - Workflow status notification system

UI Components (components/ui/)

Generic, reusable UI components:

  • IconSymbol - Cross-platform icon component (SF Symbols / Material Icons)
  • Collapsible - Expandable content container
  • OptimizedList - Performance-optimized list rendering

3. Business Logic Layer (Hooks)

useJulesApi

The main API hook that handles all Jules API communication:

const {
  isLoading,
  error,
  sources,
  fetchSessions,
  fetchActivities,
  createSession,
  approvePlan,
} = useJulesApi({ apiKey, t });

Features:

  • Automatic error handling
  • Loading state management
  • Pagination support for sources
  • Silent refresh option

GitHub Integration Hooks

Specialized hooks for GitHub functionality:

  • useGithubApi - Core GitHub API integration with Octokit
  • useGithubDeepLinking - URL parsing and deep linking for GitHub URLs
  • useGithubService - GitHub service layer abstraction
  • useGithubSession - Session creation with GitHub repository context
  • useGithubWebhooksNative - Native webhook event handling
  • useGithubWebhooks - Webhook management and processing
  • useNotifications - Push notification system for repository events
  • usePullRequestAnalysis - AI-powered PR analysis and review
  • useRepositoryManager - Repository browsing and management
  • useRepositorySync - Background synchronization with conflict resolution
  • useWorkflowUpdates - Real-time workflow status monitoring

useSecureStorage

Handles secure data persistence:

const {
  saveApiKey,
  getApiKey,
  saveTheme,
  getTheme,
  saveLanguage,
  getLanguage,
} = useSecureStorage();

4. Data Layer

Types (constants/types.ts)

Strict TypeScript definitions for all API responses:

interface Session {
  name: string;
  title?: string;
  state: "ACTIVE" | "COMPLETED" | "FAILED";
  createTime: string;
  updateTime: string;
}

interface Activity {
  name: string;
  originator: "agent" | "user";
  agentMessaged?: { agentMessage: string };
  userMessaged?: { userMessage: string };
  planGenerated?: { plan: Plan };
  // ...
}

Context Providers

ApiKeyContext - Global API key state with secure persistence

<ApiKeyProvider>
  {children}
</ApiKeyProvider>

GithubContext - GitHub integration state and configuration

<GithubProvider>
  {children}
</GithubProvider>

I18nContext - Language state and translation function

const { language, setLanguage, t } = useI18n();

5. Service Layer

GitHub Service (services/github.ts)

Centralized service layer for GitHub API operations:

  • Repository management (list, search, details)
  • Webhook configuration and event handling
  • Workflow monitoring and log retrieval
  • Pull request analysis and review
  • Authentication and token management
  • Rate limiting and error handling

Data Flow

┌────────────┐      ┌──────────────┐      ┌────────────────┐
│   Screen   │ ──▶  │  useJulesApi │ ──▶  │  Jules API     │
│            │      │    Hook      │      │ googleapis.com │
└────────────┘      └──────────────┘      └────────────────┘
      │                    │
      │                    ▼
      │             ┌──────────────┐
      │             │    State     │
      │             │  (useState)  │
      │             └──────────────┘
      │                    │
      ▼                    ▼
┌────────────┐      ┌──────────────┐
│ Components │ ◀──  │  Re-render   │
└────────────┘      └──────────────┘

State Management

Local State (useState)

Used for component-specific state:

  • Form inputs
  • UI toggles
  • Temporary data

Context (React Context)

Used for app-wide state:

  • API Key
  • Language preference
  • Theme (via Appearance API)

Persistent State (SecureStore)

Used for secure, persistent data:

  • API Key
  • User preferences

Styling Strategy

Approach

  • StyleSheet.create() for static styles
  • Conditional styles for dark mode: [styles.base, isDark && styles.dark]
  • Inline styles only for dynamic values

Color Palette

// Light Theme
background: "#f8fafc";
card: "#ffffff";
text: "#0f172a";
accent: "#2563eb";

// Dark Theme
background: "#020617";
card: "#1e293b";
text: "#f8fafc";
accent: "#60a5fa";

Performance Optimizations

  1. Memoized Components

    const MemoizedSessionCard = memo(SessionCard);

  2. FlatList Optimization

    <FlatList
  removeClippedSubviews={true}
  initialNumToRender={10}
  maxToRenderPerBatch={10}
  windowSize={5}
  getItemLayout={(_, index) => ({...})}
/>

  3. Lazy Loading

    • Sources loaded on dropdown open
    • Pagination with infinite scroll

  4. Polling Strategy

    • 5-second interval for activity updates
    • Silent refresh (no loading spinner)

Error Handling

try {
  const data = await julesFetch("/sessions");
} catch (err) {
  setError(err.message);
}
  • Errors displayed in dismissible banners
  • API errors parsed from response
  • Network errors handled gracefully

Testing Strategy

(To be implemented)

  • Unit tests for hooks
  • Component tests with React Native Testing Library
  • E2E tests with Detox