# harzva/mobilecore architecture

> Architecture diagram of the GitHub repository harzva/mobilecore, 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/harzva/mobilecore
- Repository: https://github.com/harzva/mobilecore

## Overview

MobileCore is an on-device model runtime product: users import or install a model, load it, then call local inference and inspect metrics or recommendations. Android adds a verified model catalog, local photo search, and vision/G2D evaluation; iOS provides a native runtime and local API skeleton. The separate TuiMa web game exercises MobileCore from a browser and records scores. Relationships below follow the README and shown source/index references; several Android feature internals were not sampled, so their internal links are intentionally limited.

Main entry points: [`game-web/src/App.tsx`](https://github.com/harzva/mobilecore/blob/main/game-web/src/App.tsx) (Game App), [`android-app/app/src/main/kotlin/ai/mobilecore/network/LocalApiServer.kt`](https://github.com/harzva/mobilecore/blob/main/android-app/app/src/main/kotlin/ai/mobilecore/network/LocalApiServer.kt) (Local API), [`android-app/app/src/main/kotlin/ai/mobilecore/runtime/ModelManager.kt`](https://github.com/harzva/mobilecore/blob/main/android-app/app/src/main/kotlin/ai/mobilecore/runtime/ModelManager.kt) (Model Manager), [`android-app/app/src/main/kotlin/ai/mobilecore/service/MobileCoreService.kt`](https://github.com/harzva/mobilecore/blob/main/android-app/app/src/main/kotlin/ai/mobilecore/service/MobileCoreService.kt) (Foreground Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_android_runtime["Android Runtime"]
  node_android_service["Foreground Service"]
  node_local_api["Local API<br/>[LocalApiServer.kt]"]
  node_model_manager["Model Manager<br/>[ModelManager.kt]"]
  node_gguf_metadata["GGUF Metadata"]
  node_runtime_bridge["Runtime Bridge<br/>[RuntimeBridge.kt]"]
  node_native_backend["llama.cpp Backend"]
end

subgraph group_android_features["Android Features"]
  node_playground["Model Playground"]
  node_benchmark["Benchmarks<br/>[BenchmarkScorer.kt]"]
  node_gallery["Local Gallery Search"]
  node_gallery_runtime["CLIP Runtime"]
  node_g2d_runner["G2D Evaluation"]
  node_g2d_engine["G2D Router<br/>[G2dEngine.kt]"]
end

subgraph group_ios_app["iOS App"]
  node_ios_ui["SwiftUI App<br/>[ContentView.swift]"]
  node_ios_models["Model Manager<br/>[ModelManager.swift]"]
  node_ios_api["Local API"]
  node_ios_router["API Router"]
  node_ios_runtime["Llama Runtime<br/>[LlamaRuntime.swift]"]
  node_ios_metrics[("Runtime Metrics")]
end

subgraph group_game["TuiMa Game"]
  node_game_app["Game App<br/>[App.tsx]"]
  node_game_challenge["Challenge<br/>[Challenge.tsx]"]
  node_board["Game Board<br/>[board.ts]"]
  node_scoring["Scoring<br/>[scoring.ts]"]
  node_telemetry["Device Telemetry<br/>[deviceTelemetry.ts]"]
  node_benchmark_client["MobileCore Client"]
  node_submissions[("Local Submissions<br/>[storage.ts]")]
  node_leaderboard["Shared Leaderboard"]
end

node_android_user(("Android User"))
node_ios_user(("iOS User"))
node_web_player(("Web Player"))

node_android_user -->|"starts service"| node_android_service
node_android_service -->|"starts server"| node_local_api
node_android_service -->|"creates manager"| node_model_manager
node_local_api -->|"manages models"| node_model_manager
node_model_manager -->|"reads metadata"| node_gguf_metadata
node_local_api -->|"serves inference"| node_runtime_bridge
node_runtime_bridge -->|"calls JNI"| node_native_backend
node_android_user -->|"installs model"| node_playground
node_playground -->|"places artifacts for"| node_model_manager
node_android_user -->|"runs benchmarks"| node_benchmark
node_android_user -->|"searches photos"| node_gallery
node_gallery -->|"runs CLIP inference"| node_gallery_runtime
node_android_user -->|"runs evaluation"| node_g2d_runner
node_g2d_runner -->|"routes candidates"| node_g2d_engine
node_ios_user -->|"uses app"| node_ios_ui
node_ios_ui -->|"imports models"| node_ios_models
node_ios_ui -->|"starts local API"| node_ios_api
node_ios_api -->|"routes requests"| node_ios_router
node_ios_router -->|"runs chat"| node_ios_runtime
node_ios_router -->|"lists models"| node_ios_models
node_ios_runtime -->|"updates metrics"| node_ios_metrics
node_web_player -->|"plays game"| node_game_app
node_game_app -->|"creates game state"| node_board
node_game_app -->|"calculates score"| node_scoring
node_game_app -->|"collects telemetry"| node_telemetry
node_game_app -->|"saves results"| node_submissions
node_game_app -->|"uploads results"| node_leaderboard
node_game_app -->|"renders challenge"| node_game_challenge
node_game_challenge -->|"updates state"| node_board
node_game_challenge -->|"requests inference"| node_benchmark_client
node_benchmark_client -->|"calls localhost API"| node_local_api

click node_android_service "https://github.com/harzva/mobilecore/blob/main/android-app/app/src/main/kotlin/ai/mobilecore/service/MobileCoreService.kt"
click node_local_api "https://github.com/harzva/mobilecore/blob/main/android-app/app/src/main/kotlin/ai/mobilecore/network/LocalApiServer.kt"
click node_model_manager "https://github.com/harzva/mobilecore/blob/main/android-app/app/src/main/kotlin/ai/mobilecore/runtime/ModelManager.kt"
click node_gguf_metadata "https://github.com/harzva/mobilecore/blob/main/android-app/app/src/main/kotlin/ai/mobilecore/runtime/GgufMetadataReader.kt"
click node_runtime_bridge "https://github.com/harzva/mobilecore/blob/main/android-app/app/src/main/kotlin/ai/mobilecore/runtime/RuntimeBridge.kt"
click node_native_backend "https://github.com/harzva/mobilecore/blob/main/android-app/app/src/main/cpp/mobilecore_llama_bridge.cpp"
click node_playground "https://github.com/harzva/mobilecore/blob/main/android-app/app/src/main/kotlin/ai/mobilecore/playground/PlaygroundArtifactInstaller.kt"
click node_benchmark "https://github.com/harzva/mobilecore/blob/main/android-app/app/src/main/kotlin/ai/mobilecore/runtime/BenchmarkScorer.kt"
click node_gallery "https://github.com/harzva/mobilecore/blob/main/android-app/app/src/main/kotlin/ai/mobilecore/gallery/search/GallerySearchCoordinator.kt"
click node_gallery_runtime "https://github.com/harzva/mobilecore/blob/main/android-app/app/src/main/kotlin/ai/mobilecore/gallery/search/OnnxClipGalleryRuntime.kt"
click node_g2d_runner "https://github.com/harzva/mobilecore/blob/main/android-app/app/src/main/kotlin/ai/mobilecore/g2d/OxfordPetsG2dRunner.kt"
click node_g2d_engine "https://github.com/harzva/mobilecore/blob/main/android-app/app/src/main/kotlin/ai/mobilecore/g2d/G2dEngine.kt"
click node_ios_ui "https://github.com/harzva/mobilecore/blob/main/ios-app/MobileCoreApp/ContentView.swift"
click node_ios_models "https://github.com/harzva/mobilecore/blob/main/ios-app/MobileCoreApp/Models/ModelManager.swift"
click node_ios_api "https://github.com/harzva/mobilecore/blob/main/ios-app/MobileCoreApp/API/LocalAPIServer.swift"
click node_ios_router "https://github.com/harzva/mobilecore/blob/main/ios-app/MobileCoreApp/API/OpenAICompatibleRouter.swift"
click node_ios_runtime "https://github.com/harzva/mobilecore/blob/main/ios-app/MobileCoreApp/Runtime/LlamaRuntime.swift"
click node_ios_metrics "https://github.com/harzva/mobilecore/blob/main/ios-app/MobileCoreApp/Runtime/RuntimeMetrics.swift"
click node_game_app "https://github.com/harzva/mobilecore/blob/main/game-web/src/App.tsx"
click node_game_challenge "https://github.com/harzva/mobilecore/blob/main/game-web/src/pages/Challenge.tsx"
click node_board "https://github.com/harzva/mobilecore/blob/main/game-web/src/game/board.ts"
click node_scoring "https://github.com/harzva/mobilecore/blob/main/game-web/src/game/scoring.ts"
click node_telemetry "https://github.com/harzva/mobilecore/blob/main/game-web/src/deviceTelemetry.ts"
click node_benchmark_client "https://github.com/harzva/mobilecore/blob/main/game-web/src/mobilecoreClient.ts"
click node_submissions "https://github.com/harzva/mobilecore/blob/main/game-web/src/storage.ts"
click node_leaderboard "https://github.com/harzva/mobilecore/blob/main/game-web/src/supabaseLeaderboard.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_android_service,node_local_api,node_model_manager,node_gguf_metadata,node_runtime_bridge,node_native_backend,node_android_user,node_ios_user toneBlue
class node_playground,node_benchmark,node_gallery,node_gallery_runtime,node_g2d_runner,node_g2d_engine toneAmber
class node_ios_ui,node_ios_models,node_ios_api,node_ios_router,node_ios_runtime,node_ios_metrics toneMint
class node_game_app,node_game_challenge,node_board,node_scoring,node_telemetry,node_benchmark_client,node_submissions,node_leaderboard toneRose
class node_web_player toneIndigo
```

## Components

### Android Runtime

- [Foreground Service](https://github.com/harzva/mobilecore/blob/main/android-app/app/src/main/kotlin/ai/mobilecore/service/MobileCoreService.kt): `android-app/app/src/main/kotlin/ai/mobilecore/service/MobileCoreService.kt`
- [Local API](https://github.com/harzva/mobilecore/blob/main/android-app/app/src/main/kotlin/ai/mobilecore/network/LocalApiServer.kt): `android-app/app/src/main/kotlin/ai/mobilecore/network/LocalApiServer.kt`
- [Model Manager](https://github.com/harzva/mobilecore/blob/main/android-app/app/src/main/kotlin/ai/mobilecore/runtime/ModelManager.kt): `android-app/app/src/main/kotlin/ai/mobilecore/runtime/ModelManager.kt`
- [GGUF Metadata](https://github.com/harzva/mobilecore/blob/main/android-app/app/src/main/kotlin/ai/mobilecore/runtime/GgufMetadataReader.kt): `android-app/app/src/main/kotlin/ai/mobilecore/runtime/GgufMetadataReader.kt`
- [Runtime Bridge](https://github.com/harzva/mobilecore/blob/main/android-app/app/src/main/kotlin/ai/mobilecore/runtime/RuntimeBridge.kt): `android-app/app/src/main/kotlin/ai/mobilecore/runtime/RuntimeBridge.kt`
- [llama.cpp Backend](https://github.com/harzva/mobilecore/blob/main/android-app/app/src/main/cpp/mobilecore_llama_bridge.cpp): `android-app/app/src/main/cpp/mobilecore_llama_bridge.cpp`

### Android Features

- [Model Playground](https://github.com/harzva/mobilecore/blob/main/android-app/app/src/main/kotlin/ai/mobilecore/playground/PlaygroundArtifactInstaller.kt): `android-app/app/src/main/kotlin/ai/mobilecore/playground/PlaygroundArtifactInstaller.kt`
- [Benchmarks](https://github.com/harzva/mobilecore/blob/main/android-app/app/src/main/kotlin/ai/mobilecore/runtime/BenchmarkScorer.kt): `android-app/app/src/main/kotlin/ai/mobilecore/runtime/BenchmarkScorer.kt`
- [Local Gallery Search](https://github.com/harzva/mobilecore/blob/main/android-app/app/src/main/kotlin/ai/mobilecore/gallery/search/GallerySearchCoordinator.kt): `android-app/app/src/main/kotlin/ai/mobilecore/gallery/search/GallerySearchCoordinator.kt`
- [CLIP Runtime](https://github.com/harzva/mobilecore/blob/main/android-app/app/src/main/kotlin/ai/mobilecore/gallery/search/OnnxClipGalleryRuntime.kt): `android-app/app/src/main/kotlin/ai/mobilecore/gallery/search/OnnxClipGalleryRuntime.kt`
- [G2D Evaluation](https://github.com/harzva/mobilecore/blob/main/android-app/app/src/main/kotlin/ai/mobilecore/g2d/OxfordPetsG2dRunner.kt): `android-app/app/src/main/kotlin/ai/mobilecore/g2d/OxfordPetsG2dRunner.kt`
- [G2D Router](https://github.com/harzva/mobilecore/blob/main/android-app/app/src/main/kotlin/ai/mobilecore/g2d/G2dEngine.kt): `android-app/app/src/main/kotlin/ai/mobilecore/g2d/G2dEngine.kt`

### iOS App

- [SwiftUI App](https://github.com/harzva/mobilecore/blob/main/ios-app/MobileCoreApp/ContentView.swift): `ios-app/MobileCoreApp/ContentView.swift`
- [Model Manager](https://github.com/harzva/mobilecore/blob/main/ios-app/MobileCoreApp/Models/ModelManager.swift): `ios-app/MobileCoreApp/Models/ModelManager.swift`
- [Local API](https://github.com/harzva/mobilecore/blob/main/ios-app/MobileCoreApp/API/LocalAPIServer.swift): `ios-app/MobileCoreApp/API/LocalAPIServer.swift`
- [API Router](https://github.com/harzva/mobilecore/blob/main/ios-app/MobileCoreApp/API/OpenAICompatibleRouter.swift): `ios-app/MobileCoreApp/API/OpenAICompatibleRouter.swift`
- [Llama Runtime](https://github.com/harzva/mobilecore/blob/main/ios-app/MobileCoreApp/Runtime/LlamaRuntime.swift): `ios-app/MobileCoreApp/Runtime/LlamaRuntime.swift`
- [Runtime Metrics](https://github.com/harzva/mobilecore/blob/main/ios-app/MobileCoreApp/Runtime/RuntimeMetrics.swift): `ios-app/MobileCoreApp/Runtime/RuntimeMetrics.swift`

### TuiMa Game

- [Game App](https://github.com/harzva/mobilecore/blob/main/game-web/src/App.tsx): `game-web/src/App.tsx`
- [Challenge](https://github.com/harzva/mobilecore/blob/main/game-web/src/pages/Challenge.tsx): `game-web/src/pages/Challenge.tsx`
- [Game Board](https://github.com/harzva/mobilecore/blob/main/game-web/src/game/board.ts): `game-web/src/game/board.ts`
- [Scoring](https://github.com/harzva/mobilecore/blob/main/game-web/src/game/scoring.ts): `game-web/src/game/scoring.ts`
- [Device Telemetry](https://github.com/harzva/mobilecore/blob/main/game-web/src/deviceTelemetry.ts): `game-web/src/deviceTelemetry.ts`
- [MobileCore Client](https://github.com/harzva/mobilecore/blob/main/game-web/src/mobilecoreClient.ts): `game-web/src/mobilecoreClient.ts`
- [Local Submissions](https://github.com/harzva/mobilecore/blob/main/game-web/src/storage.ts): `game-web/src/storage.ts`
- [Shared Leaderboard](https://github.com/harzva/mobilecore/blob/main/game-web/src/supabaseLeaderboard.ts): `game-web/src/supabaseLeaderboard.ts`

### Other components

- **Android User**
- **iOS User**
- **Web Player**

## Connections

- Android User → Foreground Service: starts service (evidence: `README.md`)
- Foreground Service → Local API: starts server (evidence: `android-app/app/src/main/kotlin/ai/mobilecore/service/MobileCoreService.kt`)
- Foreground Service → Model Manager: creates manager (evidence: `android-app/app/src/main/kotlin/ai/mobilecore/service/MobileCoreService.kt`)
- Local API → Model Manager: manages models (evidence: `README.md`)
- Model Manager → GGUF Metadata: reads metadata (evidence: `android-app/app/src/main/kotlin/ai/mobilecore/runtime/ModelManager.kt`)
- Local API → Runtime Bridge: serves inference (evidence: `README.md`)
- Runtime Bridge → llama.cpp Backend: calls JNI (evidence: `README.md`)
- Android User → Model Playground: installs model (evidence: `README.md`)
- Model Playground → Model Manager: places artifacts for (evidence: `README.md`)
- Android User → Benchmarks: runs benchmarks (evidence: `README.md`)
- Android User → Local Gallery Search: searches photos (evidence: `README.md`)
- Local Gallery Search → CLIP Runtime: runs CLIP inference (evidence: `README.md`)
- Android User → G2D Evaluation: runs evaluation (evidence: `README.md`)
- G2D Evaluation → G2D Router: routes candidates
- iOS User → SwiftUI App: uses app (evidence: `README.md`)
- SwiftUI App → Model Manager: imports models (evidence: `ios-app/MobileCoreApp/MobileCoreApp.swift`)
- SwiftUI App → Local API: starts local API (evidence: `ios-app/MobileCoreApp/MobileCoreApp.swift`)
- Local API → API Router: routes requests (evidence: `ios-app/MobileCoreApp/API/LocalAPIServer.swift`)
- API Router → Llama Runtime: runs chat (evidence: `ios-app/MobileCoreApp/API/OpenAICompatibleRouter.swift`)
- API Router → Model Manager: lists models (evidence: `ios-app/MobileCoreApp/API/OpenAICompatibleRouter.swift`)
- Llama Runtime → Runtime Metrics: updates metrics (evidence: `ios-app/MobileCoreApp/Runtime/LlamaRuntime.swift`)
- Web Player → Game App: plays game (evidence: `README.md`)
- Game App → Game Board: creates game state (evidence: `game-web/src/App.tsx`)
- Game App → Scoring: calculates score (evidence: `game-web/src/App.tsx`)
- Game App → Device Telemetry: collects telemetry (evidence: `game-web/src/App.tsx`)
- Game App → Local Submissions: saves results (evidence: `game-web/src/App.tsx`)
- Game App → Shared Leaderboard: uploads results (evidence: `game-web/src/App.tsx`)
- Game App → Challenge: renders challenge (evidence: `game-web/src/App.tsx`)
- Challenge → Game Board: updates state (evidence: `game-web/src/pages/Challenge.tsx`)
- Challenge → MobileCore Client: requests inference (evidence: `game-web/src/pages/Challenge.tsx`)
- MobileCore Client → Local API: calls localhost API (evidence: `README.md`)
