# a-ghorbani/pocketpal-ai architecture

> Architecture diagram of the GitHub repository a-ghorbani/pocketpal-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/a-ghorbani/pocketpal-ai
- Repository: https://github.com/a-ghorbani/pocketpal-ai

## Overview

##### Main Components

a. Frontend Layer:
- React Native UI Components (src/components)
- Screens (src/screens)
- Chat Screen
- Models Screen
- Settings Screen
- Benchmark Screen

b. State Management Layer:
- MobX Stores (src/store)
- ModelStore
- ChatSessionStore
- BenchmarkStore
- UIStore
- HFStore

c. Core Services:
- Model Management System
- Hugging Face Integration
- Local Storage System
- Device Info Services

d. External Integrations:
- llama.cpp (via llama.rn bindings)
- Hugging Face Hub API
- Firebase App Check

**┌─ User Interface Layer ─────────────────────┐**
- ┌─ Screens ─┐  ┌─ Core Components ───────┐ │
- Chat       │  │Avatar    │Dialog        │ │
- Models     │  │ChatInput │MarkdownView  │ │
- Settings   │  │Bubble    │TextMessage   │ │
- Benchmark  │  │...       │...           │ │
- ┘  └────────────────────────┘ │
- State Management Layer ──────────────────┤
- ┌─ MobX Stores ────────────────────────┐  │
- ModelStore    │ChatSessionStore       │  │
- BenchmarkStore│UIStore               │  │
- HFStore      │                       │  │
- ┘  │
- Core Services Layer ───────────────────┤
- ┌─ Model Management ─┐ ┌─ Storage ────┐ │
- Download           │ │AsyncStorage   │ │
- Load/Unload       │ │File System    │ │
- Inference         │ │               │ │
- ┘ └──────────────┘ │
- Native Bridge Layer ─────────────────┤
- ┌─ Platform Specific ─────────────────┐ │
- iOS Native Modules │Android Native   │ │
- Device Info       │Modules          │ │
- ┘ │
- External Dependencies ────────────────┘
- llama.cpp/llama.rn│Firebase AppCheck│
- Hugging Face API  │                 │
- ┘

##### Key Relationships to Highlight

- User interface components (blue)
- State management (green)
- Core services (orange)
- External dependencies (gray)

##### Important Details

- Offline capability workflow
- Model loading/unloading cycle
- Memory management flow
- Data persistence paths
- Platform-specific implementations

##### Implementation Notes

- Maintain consistent styling throughout
- Brief annotations for complex interactions
- Creating separate detailed views for critical subsystems

##### Key Workflows to Highlight

- Model download and initialization process
- Chat session management
- Memory optimization cycle
- Hugging Face model integration
- Platform-specific native module interactions

Remember to emphasize the unique aspects of PocketPal AI, such as its ability to run models directly on device and the automatic memory management system.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles and Classes
    classDef ui fill:#e1f5fe,stroke:#01579b
    classDef store fill:#e8f5e9,stroke:#1b5e20
    classDef service fill:#fff3e0,stroke:#e65100
    classDef external fill:#f5f5f5,stroke:#424242
    classDef native fill:#f3e5f5,stroke:#4a148c

    %% User Interface Layer
    subgraph UI[User Interface Layer]
        subgraph Screens
            ChatScreen["Chat Screen"]
            ModelsScreen["Models Screen"]
            SettingsScreen["Settings Screen"]
            BenchmarkScreen["Benchmark Screen"]
        end

        subgraph Components
            Avatar["Avatar"]
            ChatInput["Chat Input"]
            Bubble["Bubble"]
            MarkdownView["Markdown View"]
            TextMessage["Text Message"]
        end
    end

    %% State Management Layer
    subgraph StateManagement[State Management Layer]
        ModelStore["Model Store"]
        ChatSessionStore["Chat Session Store"]
        BenchmarkStore["Benchmark Store"]
        UIStore["UI Store"]
        HFStore["HF Store"]
    end

    %% Core Services Layer
    subgraph CoreServices[Core Services Layer]
        subgraph ModelManagement[Model Management]
            Download["Download Service"]
            LoadUnload["Load/Unload Service"]
            Inference["Inference Engine"]
        end

        subgraph Storage[Storage Services]
            AsyncStorage["Async Storage"]
            FileSystem["File System"]
        end

        HFIntegration["Hugging Face Integration"]
        BenchmarkService["Benchmark Service"]
    end

    %% Native Bridge Layer
    subgraph NativeBridge[Native Bridge Layer]
        iOSNative["iOS Native Module"]
        AndroidNative["Android Native Module"]
        DeviceInfo["Device Info Services"]
    end

    %% External Dependencies
    subgraph External[External Dependencies]
        LlamaCpp["llama.cpp/llama.rn"]
        FirebaseAppCheck["Firebase AppCheck"]
        HFApi["Hugging Face API"]
    end

    %% Relationships
    ChatScreen --> ChatSessionStore
    ModelsScreen --> ModelStore
    BenchmarkScreen --> BenchmarkStore
    SettingsScreen --> UIStore

    ModelStore --> HFIntegration
    ChatSessionStore --> Inference
    BenchmarkStore --> BenchmarkService

    HFIntegration --> HFApi
    Inference --> LlamaCpp
    DeviceInfo --> ModelStore

    %% Click Events
    click ChatScreen "https://github.com/a-ghorbani/pocketpal-ai/blob/main/src/screens/ChatScreen/ChatScreen.tsx"
    click ModelsScreen "https://github.com/a-ghorbani/pocketpal-ai/blob/main/src/screens/ModelsScreen/ModelsScreen.tsx"
    click SettingsScreen "https://github.com/a-ghorbani/pocketpal-ai/blob/main/src/screens/SettingsScreen/SettingsScreen.tsx"
    click BenchmarkScreen "https://github.com/a-ghorbani/pocketpal-ai/blob/main/src/screens/BenchmarkScreen/BenchmarkScreen.tsx"
    click Components "https://github.com/a-ghorbani/pocketpal-ai/tree/main/src/components/"
    click ModelStore "https://github.com/a-ghorbani/pocketpal-ai/blob/main/src/store/ModelStore.ts"
    click ChatSessionStore "https://github.com/a-ghorbani/pocketpal-ai/blob/main/src/store/ChatSessionStore.ts"
    click BenchmarkStore "https://github.com/a-ghorbani/pocketpal-ai/blob/main/src/store/BenchmarkStore.ts"
    click UIStore "https://github.com/a-ghorbani/pocketpal-ai/blob/main/src/store/UIStore.ts"
    click HFStore "https://github.com/a-ghorbani/pocketpal-ai/blob/main/src/store/HFStore.ts"
    click HFIntegration "https://github.com/a-ghorbani/pocketpal-ai/blob/main/src/api/hf.ts"
    click BenchmarkService "https://github.com/a-ghorbani/pocketpal-ai/blob/main/src/api/benchmark.ts"
    click FirebaseAppCheck "https://github.com/a-ghorbani/pocketpal-ai/blob/main/src/utils/fb.ts"
    click iOSNative "https://github.com/a-ghorbani/pocketpal-ai/blob/main/ios/PocketPal/DeviceInfoModule.m"
    click AndroidNative "https://github.com/a-ghorbani/pocketpal-ai/blob/main/android/app/src/main/java/com/pocketpalai/DeviceInfoModule.kt"

    %% Apply Classes
    class ChatScreen,ModelsScreen,SettingsScreen,BenchmarkScreen,Avatar,ChatInput,Bubble,MarkdownView,TextMessage ui
    class ModelStore,ChatSessionStore,BenchmarkStore,UIStore,HFStore store
    class Download,LoadUnload,Inference,AsyncStorage,FileSystem,HFIntegration,BenchmarkService service
    class LlamaCpp,FirebaseAppCheck,HFApi external
    class iOSNative,AndroidNative,DeviceInfo native
```
