# rushb-fr/freekiosk architecture

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

- Interactive diagram: https://gitdiagram.com/rushb-fr/freekiosk
- Repository: https://github.com/rushb-fr/freekiosk

## Overview

FreeKiosk is an Android kiosk platform with a React Native control UI and Kotlin system-control layer. The main workflow is configuring a kiosk, persisting settings, and running the selected WebView, external-app, or dashboard experience under device lockdown; REST, MQTT, and optional cloud fleet management extend that runtime. The map preserves documented scheduling, media, printing, and managed-app capabilities. Some implementation links rely on README statements or SOURCE INDEX references because their source was not excerpted.

Main entry points: [`src/screens/KioskScreen.tsx`](https://github.com/rushb-fr/freekiosk/blob/main/src/screens/KioskScreen.tsx) (Kiosk runtime), [`android/app/src/main/java/com/freekiosk/MainActivity.kt`](https://github.com/rushb-fr/freekiosk/blob/main/android/app/src/main/java/com/freekiosk/MainActivity.kt) (Android activity), [`src/utils/storage.ts`](https://github.com/rushb-fr/freekiosk/blob/main/src/utils/storage.ts) (Configuration storage), [`src/navigation/AppNavigator.tsx`](https://github.com/rushb-fr/freekiosk/blob/main/src/navigation/AppNavigator.tsx) (App navigation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Kiosk experience"]
  node_navigation["App navigation<br/>[AppNavigator.tsx]"]
  node_kiosk["Kiosk runtime<br/>[KioskScreen.tsx]"]
  node_webview["WebView mode"]
  node_dashboard["Dashboard mode<br/>[dashboard.ts]"]
  node_media["Media player<br/>[mediaPlayer.ts]"]
  node_managed["Managed apps<br/>[managedApps.ts]"]
end

subgraph group_controls["Configuration and control"]
  node_settings["Settings UI"]
  node_overlays["Blocking overlays"]
  node_scheduler["Screen scheduler<br/>[screenScheduler.ts]"]
  node_storage[("Configuration storage<br/>[storage.ts]")]
  node_secrets["Secure credentials<br/>[secureStorage.ts]"]
  node_devicecontrol["Device control service"]
end

subgraph group_android["Android enforcement"]
  node_nativekiosk["Kiosk native module<br/>[KioskModule.kt]"]
  node_activity["Android activity<br/>[MainActivity.kt]"]
  node_watchdog["Kiosk watchdog"]
  node_overlayservice["Overlay service<br/>[OverlayService.kt]"]
end

subgraph group_integrations["Automation and fleet"]
  node_rest["REST API<br/>[ApiService.ts]"]
  node_mqtt["MQTT integration<br/>[KioskMqttClient.kt]"]
  node_cloud["Cloud fleet sync"]
  node_printer["Silent printing"]
end

node_operator(("Device operator"))

node_operator -->|"opens app"| node_navigation
node_navigation -->|"starts at"| node_kiosk
node_navigation -->|"routes to"| node_settings
node_kiosk -->|"renders mode"| node_webview
node_kiosk -->|"loads settings"| node_storage
node_settings -->|"persists settings"| node_storage
node_storage -->|"stores credentials"| node_secrets
node_kiosk -->|"controls kiosk"| node_nativekiosk
node_activity -->|"hosts module"| node_nativekiosk
node_activity -->|"starts service"| node_watchdog
node_watchdog -->|"relaunches"| node_activity
node_activity -->|"starts service"| node_overlayservice
node_activity -->|"uses manager"| node_overlays
node_kiosk -->|"controls device"| node_devicecontrol
node_kiosk -->|"supports mode"| node_dashboard
node_kiosk -->|"supports mode"| node_media
node_kiosk -->|"supports apps"| node_managed
node_settings -->|"configures schedule"| node_scheduler
node_operator -->|"configures remotely"| node_rest
node_rest -.->|"controls device"| node_devicecontrol
node_operator -->|"integrates automation"| node_mqtt
node_operator -->|"opts into fleet"| node_cloud
node_cloud -->|"applies config"| node_storage
node_cloud -->|"loads credentials"| node_secrets
node_kiosk -->|"supports printing"| node_printer

click node_navigation "https://github.com/rushb-fr/freekiosk/blob/main/src/navigation/AppNavigator.tsx"
click node_kiosk "https://github.com/rushb-fr/freekiosk/blob/main/src/screens/KioskScreen.tsx"
click node_webview "https://github.com/rushb-fr/freekiosk/blob/main/src/components/WebViewComponent.tsx"
click node_dashboard "https://github.com/rushb-fr/freekiosk/blob/main/src/types/dashboard.ts"
click node_media "https://github.com/rushb-fr/freekiosk/blob/main/src/types/mediaPlayer.ts"
click node_managed "https://github.com/rushb-fr/freekiosk/blob/main/src/types/managedApps.ts"
click node_settings "https://github.com/rushb-fr/freekiosk/blob/main/src/screens/settings/SettingsScreenNew.tsx"
click node_overlays "https://github.com/rushb-fr/freekiosk/blob/main/android/app/src/main/java/com/freekiosk/BlockingOverlayManager.kt"
click node_scheduler "https://github.com/rushb-fr/freekiosk/blob/main/src/types/screenScheduler.ts"
click node_storage "https://github.com/rushb-fr/freekiosk/blob/main/src/utils/storage.ts"
click node_secrets "https://github.com/rushb-fr/freekiosk/blob/main/src/utils/secureStorage.ts"
click node_devicecontrol "https://github.com/rushb-fr/freekiosk/blob/main/src/services/DeviceControlService.ts"
click node_nativekiosk "https://github.com/rushb-fr/freekiosk/blob/main/android/app/src/main/java/com/freekiosk/KioskModule.kt"
click node_activity "https://github.com/rushb-fr/freekiosk/blob/main/android/app/src/main/java/com/freekiosk/MainActivity.kt"
click node_watchdog "https://github.com/rushb-fr/freekiosk/blob/main/android/app/src/main/java/com/freekiosk/KioskWatchdogService.kt"
click node_overlayservice "https://github.com/rushb-fr/freekiosk/blob/main/android/app/src/main/java/com/freekiosk/OverlayService.kt"
click node_rest "https://github.com/rushb-fr/freekiosk/blob/main/src/utils/ApiService.ts"
click node_mqtt "https://github.com/rushb-fr/freekiosk/blob/main/android/app/src/main/java/com/freekiosk/mqtt/KioskMqttClient.kt"
click node_cloud "https://github.com/rushb-fr/freekiosk/blob/main/src/utils/CloudSyncService.ts"
click node_printer "https://github.com/rushb-fr/freekiosk/blob/main/android/app/src/main/java/com/freekiosk/printing/SilentPrintModule.kt"

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_navigation,node_kiosk,node_webview,node_dashboard,node_media,node_managed toneBlue
class node_settings,node_overlays,node_scheduler,node_storage,node_secrets,node_devicecontrol toneAmber
class node_nativekiosk,node_activity,node_watchdog,node_overlayservice toneMint
class node_rest,node_mqtt,node_cloud,node_printer toneRose
class node_operator toneIndigo
```

## Components

### Kiosk experience

- [App navigation](https://github.com/rushb-fr/freekiosk/blob/main/src/navigation/AppNavigator.tsx): `src/navigation/AppNavigator.tsx`
- [Kiosk runtime](https://github.com/rushb-fr/freekiosk/blob/main/src/screens/KioskScreen.tsx): `src/screens/KioskScreen.tsx`
- [WebView mode](https://github.com/rushb-fr/freekiosk/blob/main/src/components/WebViewComponent.tsx): `src/components/WebViewComponent.tsx`
- [Dashboard mode](https://github.com/rushb-fr/freekiosk/blob/main/src/types/dashboard.ts): `src/types/dashboard.ts`
- [Media player](https://github.com/rushb-fr/freekiosk/blob/main/src/types/mediaPlayer.ts): `src/types/mediaPlayer.ts`
- [Managed apps](https://github.com/rushb-fr/freekiosk/blob/main/src/types/managedApps.ts): `src/types/managedApps.ts`

### Configuration and control

- [Settings UI](https://github.com/rushb-fr/freekiosk/blob/main/src/screens/settings/SettingsScreenNew.tsx): `src/screens/settings/SettingsScreenNew.tsx`
- [Blocking overlays](https://github.com/rushb-fr/freekiosk/blob/main/android/app/src/main/java/com/freekiosk/BlockingOverlayManager.kt): `android/app/src/main/java/com/freekiosk/BlockingOverlayManager.kt`
- [Screen scheduler](https://github.com/rushb-fr/freekiosk/blob/main/src/types/screenScheduler.ts): `src/types/screenScheduler.ts`
- [Configuration storage](https://github.com/rushb-fr/freekiosk/blob/main/src/utils/storage.ts): `src/utils/storage.ts`
- [Secure credentials](https://github.com/rushb-fr/freekiosk/blob/main/src/utils/secureStorage.ts): `src/utils/secureStorage.ts`
- [Device control service](https://github.com/rushb-fr/freekiosk/blob/main/src/services/DeviceControlService.ts): `src/services/DeviceControlService.ts`

### Android enforcement

- [Kiosk native module](https://github.com/rushb-fr/freekiosk/blob/main/android/app/src/main/java/com/freekiosk/KioskModule.kt): `android/app/src/main/java/com/freekiosk/KioskModule.kt`
- [Android activity](https://github.com/rushb-fr/freekiosk/blob/main/android/app/src/main/java/com/freekiosk/MainActivity.kt): `android/app/src/main/java/com/freekiosk/MainActivity.kt`
- [Kiosk watchdog](https://github.com/rushb-fr/freekiosk/blob/main/android/app/src/main/java/com/freekiosk/KioskWatchdogService.kt): `android/app/src/main/java/com/freekiosk/KioskWatchdogService.kt`
- [Overlay service](https://github.com/rushb-fr/freekiosk/blob/main/android/app/src/main/java/com/freekiosk/OverlayService.kt): `android/app/src/main/java/com/freekiosk/OverlayService.kt`

### Automation and fleet

- [REST API](https://github.com/rushb-fr/freekiosk/blob/main/src/utils/ApiService.ts): `src/utils/ApiService.ts`
- [MQTT integration](https://github.com/rushb-fr/freekiosk/blob/main/android/app/src/main/java/com/freekiosk/mqtt/KioskMqttClient.kt): `android/app/src/main/java/com/freekiosk/mqtt/KioskMqttClient.kt`
- [Cloud fleet sync](https://github.com/rushb-fr/freekiosk/blob/main/src/utils/CloudSyncService.ts): `src/utils/CloudSyncService.ts`
- [Silent printing](https://github.com/rushb-fr/freekiosk/blob/main/android/app/src/main/java/com/freekiosk/printing/SilentPrintModule.kt): `android/app/src/main/java/com/freekiosk/printing/SilentPrintModule.kt`

### Other components

- **Device operator**

## Connections

- Device operator → App navigation: opens app (evidence: `README.md`)
- App navigation → Kiosk runtime: starts at (evidence: `src/navigation/AppNavigator.tsx`)
- App navigation → Settings UI: routes to (evidence: `src/navigation/AppNavigator.tsx`)
- Kiosk runtime → WebView mode: renders mode (evidence: `src/screens/KioskScreen.tsx`)
- Kiosk runtime → Configuration storage: loads settings (evidence: `src/screens/KioskScreen.tsx`)
- Settings UI → Configuration storage: persists settings (evidence: `src/screens/settings/SettingsScreenNew.tsx`)
- Configuration storage → Secure credentials: stores credentials (evidence: `src/utils/storage.ts`)
- Kiosk runtime → Kiosk native module: controls kiosk (evidence: `src/screens/KioskScreen.tsx`)
- Android activity → Kiosk native module: hosts module (evidence: `android/app/src/main/java/com/freekiosk/MainActivity.kt`)
- Android activity → Kiosk watchdog: starts service (evidence: `android/app/src/main/java/com/freekiosk/MainActivity.kt`)
- Kiosk watchdog → Android activity: relaunches (evidence: `android/app/src/main/java/com/freekiosk/KioskWatchdogService.kt`)
- Android activity → Overlay service: starts service (evidence: `android/app/src/main/java/com/freekiosk/MainActivity.kt`)
- Android activity → Blocking overlays: uses manager (evidence: `android/app/src/main/java/com/freekiosk/MainActivity.kt`)
- Kiosk runtime → Device control service: controls device (evidence: `src/screens/KioskScreen.tsx`)
- Kiosk runtime → Dashboard mode: supports mode (evidence: `README.md`)
- Kiosk runtime → Media player: supports mode (evidence: `README.md`)
- Kiosk runtime → Managed apps: supports apps (evidence: `README.md`)
- Settings UI → Screen scheduler: configures schedule (evidence: `src/screens/settings/SettingsScreenNew.tsx`)
- Device operator → REST API: configures remotely (evidence: `README.md`)
- REST API → Device control service: controls device
- Device operator → MQTT integration: integrates automation (evidence: `README.md`)
- Device operator → Cloud fleet sync: opts into fleet (evidence: `README.md`)
- Cloud fleet sync → Configuration storage: applies config (evidence: `src/utils/CloudSyncService.ts`)
- Cloud fleet sync → Secure credentials: loads credentials (evidence: `src/utils/CloudSyncService.ts`)
- Kiosk runtime → Silent printing: supports printing (evidence: `README.md`)
