# brentonbluehouse/pocketpal-ai architecture

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

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

## Overview

PocketPal AI is a React Native mobile assistant centered on private, on-device model use. The principal workflow is to find and download a model, load it, then chat; chat turns can dispatch Pal-enabled tools and return their results to the model. Other documented capabilities include personalized Pals and PalsHub, speech, benchmarking, and Hugging Face access. The graph combines README-documented product flows with source-index and excerpt evidence; some subsystem internals are unsampled, so their links are limited to documented relationships.

Main entry points: [`src/hooks/useChatSession.ts`](https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/hooks/useChatSession.ts) (Chat turn orchestration), [`src/services/talents/index.ts`](https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/services/talents/index.ts) (Talent registry), [`src/screens/ChatScreen/ChatScreen.tsx`](https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/screens/ChatScreen/ChatScreen.tsx) (Chat experience), [`src/screens/ModelsScreen/ModelsScreen.tsx`](https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/screens/ModelsScreen/ModelsScreen.tsx) (Model discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and chat"]
  node_app["Mobile app<br/>[App.tsx]"]
  node_chat["Chat experience<br/>[ChatScreen.tsx]"]
  node_chatflow["Chat turn orchestration<br/>[useChatSession.ts]"]
  node_sessionstate["Session state"]
  node_sessionrepo["Session persistence"]
  node_database[("App database<br/>[schema.ts]")]
end

subgraph group_models["Models and inference"]
  node_modelsui["Model discovery<br/>[ModelsScreen.tsx]"]
  node_hfapi["Hugging Face API<br/>[hf.ts]"]
  node_downloads["Model downloads<br/>[DownloadManager.ts]"]
  node_nativeinfer["Native inference bridge"]
  node_completion["Completion engines"]
  node_modelstate["Model state<br/>[ModelStore.ts]"]
end

subgraph group_assistant["Assistant features"]
  node_talents["Talent registry<br/>[index.ts]"]
  node_search["Web search talent<br/>[WebSearchEngine.ts]"]
  node_readurl["URL reader talent<br/>[ReadUrlEngine.ts]"]
  node_calc["Calculator talent<br/>[CalculateEngine.ts]"]
  node_tts["Speech engines<br/>[engineRegistry.ts]"]
  node_benchmark["Device benchmarking"]
end

subgraph group_market["Pals marketplace"]
  node_palstate["Pal configuration<br/>[PalStore.ts]"]
  node_palrepo["Pal persistence<br/>[PalRepository.ts]"]
  node_hub["PalsHub services"]
  node_checkout["Pal checkout"]
end

subgraph group_platform["Native platform"]
  node_native{{"Phone hardware"}}
end

node_user(("App user"))
node_leaderboard["AI Phone Leaderboard"]
node_hf["Hugging Face Hub"]

node_user -->|"uses"| node_app
node_app -->|"opens chat"| node_chat
node_user -->|"selects model"| node_modelsui
node_modelsui -.->|"searches models"| node_hfapi
node_hfapi -.->|"queries"| node_hf
node_modelsui -.->|"starts download"| node_downloads
node_downloads -.->|"provides model"| node_nativeinfer
node_user -->|"sends prompt"| node_chat
node_chat -->|"submits turn"| node_chatflow
node_chatflow -->|"requests completion"| node_completion
node_completion -.->|"runs inference"| node_nativeinfer
node_chatflow -->|"dispatches tools"| node_talents
node_talents -->|"registers engine"| node_search
node_talents -->|"registers engine"| node_readurl
node_talents -->|"registers engine"| node_calc
node_search -->|"allows result URLs"| node_readurl
node_chatflow -->|"updates turns"| node_sessionstate
node_sessionstate -->|"persists sessions"| node_sessionrepo
node_sessionrepo -->|"reads and writes"| node_database
node_chat -.->|"speaks responses"| node_tts
node_user -->|"runs benchmark"| node_benchmark
node_benchmark -->|"measures device"| node_native
node_benchmark -->|"shares opt-in results"| node_leaderboard
node_user -->|"configures Pals"| node_palstate
node_palstate -->|"persists Pals"| node_palrepo
node_user -->|"browses Pals"| node_hub
node_hub -.->|"starts purchase"| node_checkout

click node_app "https://github.com/brentonbluehouse/pocketpal-ai/blob/main/App.tsx"
click node_chat "https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/screens/ChatScreen/ChatScreen.tsx"
click node_chatflow "https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/hooks/useChatSession.ts"
click node_sessionstate "https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/store/ChatSessionStore.ts"
click node_sessionrepo "https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/repositories/ChatSessionRepository.ts"
click node_database "https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/database/schema.ts"
click node_modelsui "https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/screens/ModelsScreen/ModelsScreen.tsx"
click node_hfapi "https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/api/hf.ts"
click node_downloads "https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/services/downloads/DownloadManager.ts"
click node_nativeinfer "https://github.com/brentonbluehouse/pocketpal-ai/blob/main/ios/PocketPal/AppIntents/LlamaInferenceEngine.swift"
click node_completion "https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/api/completionEngines.ts"
click node_modelstate "https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/store/ModelStore.ts"
click node_talents "https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/services/talents/index.ts"
click node_search "https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/services/talents/WebSearchEngine.ts"
click node_readurl "https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/services/talents/ReadUrlEngine.ts"
click node_calc "https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/services/talents/CalculateEngine.ts"
click node_tts "https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/services/tts/engineRegistry.ts"
click node_benchmark "https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/screens/BenchmarkScreen/BenchmarkScreen.tsx"
click node_palstate "https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/store/PalStore.ts"
click node_palrepo "https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/repositories/PalRepository.ts"
click node_hub "https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/services/palshub/PalsHubApiService.ts"
click node_checkout "https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/store/CheckoutFlowStore.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_chat,node_chatflow,node_sessionstate,node_sessionrepo,node_database,node_user toneBlue
class node_modelsui,node_hfapi,node_downloads,node_nativeinfer,node_completion,node_modelstate toneAmber
class node_talents,node_search,node_readurl,node_calc,node_tts,node_benchmark toneMint
class node_palstate,node_palrepo,node_hub,node_checkout toneRose
class node_native,node_leaderboard,node_hf toneIndigo
```

## Components

### App and chat

- [Mobile app](https://github.com/brentonbluehouse/pocketpal-ai/blob/main/App.tsx): `App.tsx`
- [Chat experience](https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/screens/ChatScreen/ChatScreen.tsx): `src/screens/ChatScreen/ChatScreen.tsx`
- [Chat turn orchestration](https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/hooks/useChatSession.ts): `src/hooks/useChatSession.ts`
- [Session state](https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/store/ChatSessionStore.ts): `src/store/ChatSessionStore.ts`
- [Session persistence](https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/repositories/ChatSessionRepository.ts): `src/repositories/ChatSessionRepository.ts`
- [App database](https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/database/schema.ts): `src/database/schema.ts`

### Models and inference

- [Model discovery](https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/screens/ModelsScreen/ModelsScreen.tsx): `src/screens/ModelsScreen/ModelsScreen.tsx`
- [Hugging Face API](https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/api/hf.ts): `src/api/hf.ts`
- [Model downloads](https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/services/downloads/DownloadManager.ts): `src/services/downloads/DownloadManager.ts`
- [Native inference bridge](https://github.com/brentonbluehouse/pocketpal-ai/blob/main/ios/PocketPal/AppIntents/LlamaInferenceEngine.swift): `ios/PocketPal/AppIntents/LlamaInferenceEngine.swift`
- [Completion engines](https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/api/completionEngines.ts): `src/api/completionEngines.ts`
- [Model state](https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/store/ModelStore.ts): `src/store/ModelStore.ts`

### Assistant features

- [Talent registry](https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/services/talents/index.ts): `src/services/talents/index.ts`
- [Web search talent](https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/services/talents/WebSearchEngine.ts): `src/services/talents/WebSearchEngine.ts`
- [URL reader talent](https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/services/talents/ReadUrlEngine.ts): `src/services/talents/ReadUrlEngine.ts`
- [Calculator talent](https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/services/talents/CalculateEngine.ts): `src/services/talents/CalculateEngine.ts`
- [Speech engines](https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/services/tts/engineRegistry.ts): `src/services/tts/engineRegistry.ts`
- [Device benchmarking](https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/screens/BenchmarkScreen/BenchmarkScreen.tsx): `src/screens/BenchmarkScreen/BenchmarkScreen.tsx`

### Pals marketplace

- [Pal configuration](https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/store/PalStore.ts): `src/store/PalStore.ts`
- [Pal persistence](https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/repositories/PalRepository.ts): `src/repositories/PalRepository.ts`
- [PalsHub services](https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/services/palshub/PalsHubApiService.ts): `src/services/palshub/PalsHubApiService.ts`
- [Pal checkout](https://github.com/brentonbluehouse/pocketpal-ai/blob/main/src/store/CheckoutFlowStore.ts): `src/store/CheckoutFlowStore.ts`

### Native platform

- **Phone hardware**

### Other components

- **App user**
- **AI Phone Leaderboard**
- **Hugging Face Hub**

## Connections

- App user → Mobile app: uses
- Mobile app → Chat experience: opens chat (evidence: `App.tsx`)
- App user → Model discovery: selects model
- Model discovery → Hugging Face API: searches models
- Hugging Face API → Hugging Face Hub: queries
- Model discovery → Model downloads: starts download
- Model downloads → Native inference bridge: provides model
- App user → Chat experience: sends prompt
- Chat experience → Chat turn orchestration: submits turn
- Chat turn orchestration → Completion engines: requests completion (evidence: `src/hooks/useChatSession.ts`)
- Completion engines → Native inference bridge: runs inference
- Chat turn orchestration → Talent registry: dispatches tools (evidence: `src/hooks/useChatSession.ts`)
- Talent registry → Web search talent: registers engine (evidence: `src/services/talents/index.ts`)
- Talent registry → URL reader talent: registers engine (evidence: `src/services/talents/index.ts`)
- Talent registry → Calculator talent: registers engine (evidence: `src/services/talents/index.ts`)
- Web search talent → URL reader talent: allows result URLs (evidence: `src/services/talents/WebSearchEngine.ts`)
- Chat turn orchestration → Session state: updates turns (evidence: `src/hooks/useChatSession.ts`)
- Session state → Session persistence: persists sessions (evidence: `src/store/ChatSessionStore.ts`)
- Session persistence → App database: reads and writes (evidence: `src/repositories/ChatSessionRepository.ts`)
- Chat experience → Speech engines: speaks responses
- App user → Device benchmarking: runs benchmark
- Device benchmarking → Phone hardware: measures device
- Device benchmarking → AI Phone Leaderboard: shares opt-in results
- App user → Pal configuration: configures Pals
- Pal configuration → Pal persistence: persists Pals
- App user → PalsHub services: browses Pals
- PalsHub services → Pal checkout: starts purchase
