# gotxe/monkiosk architecture

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

- Interactive diagram: https://gitdiagram.com/gotxe/monkiosk
- Repository: https://github.com/gotxe/monkiosk

## Overview

Monkiosk presents managed content on kiosk screens and provides a web console for kiosk health, server status, remote controls, access policy, and document management. Its core loop is kiosk presentation → heartbeat report → dashboard state, with kiosks polling for pending actions. Separate branches cover content administration, server operations, and kiosk provisioning/heartbeat services. Evidence is limited to the README and supplied excerpts/SOURCE INDEX; unsampled subsystems are included only where documented, with no inferred implementation links.

Main entry points: [`estado_quioscos/update_status.php`](https://github.com/gotxe/monkiosk/blob/main/estado_quioscos/update_status.php) (Heartbeat intake), [`estado_quioscos/docs_api.php`](https://github.com/gotxe/monkiosk/blob/main/estado_quioscos/docs_api.php) (Document API), [`kiosk_info/index.php`](https://github.com/gotxe/monkiosk/blob/main/kiosk_info/index.php) (Manual viewer), [`estado_quioscos/index.html`](https://github.com/gotxe/monkiosk/blob/main/estado_quioscos/index.html) (Status dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Kiosk presentation"]
  node_presentation_app["Content presentation<br/>[index.php]"]
  node_content_files["Presentation files"]
end

subgraph group_monitoring["Monitoring and control"]
  node_dashboard["Status dashboard<br/>[index.html]"]
  node_status_ingest["Heartbeat intake<br/>[update_status.php]"]
  node_status_store[("Kiosk status state<br/>[app_config.php]")]
  node_action_poll["Pending actions<br/>[get_action.php]"]
  node_kiosk_policy["Kiosk access policy<br/>[allowed_kiosks.php]"]
  node_policy_api["Policy API"]
  node_server_health["Server health<br/>[server_status.php]"]
  node_server_control["Server controls<br/>[server_control.php]"]
  node_auth["Session authentication<br/>[auth_lib.php]"]
end

subgraph group_content["Content and documentation"]
  node_doc_manager["Document manager<br/>[docs_manager.php]"]
  node_doc_api["Document API<br/>[docs_api.php]"]
  node_doc_preview["Document preview<br/>[docs_preview.php]"]
  node_docs_store["Managed documents"]
  node_manual_viewer["Manual viewer<br/>[index.php]"]
  node_manual_files["Manual files"]
end

subgraph group_device["Kiosk heartbeat and setup"]
  node_heartbeat["Heartbeat reporter<br/>[report_status.sh]"]
  node_alpine_heartbeat["Alpine heartbeat service"]
  node_alpine_setup["Alpine kiosk installer<br/>[setup_quiosco.sh]"]
  node_installer_report["Reporter installer<br/>[install_report.sh]"]
end

node_operator(("Operator"))
node_kiosk(("Kiosk device"))

node_kiosk -->|"opens content"| node_presentation_app
node_presentation_app -->|"reads files"| node_content_files
node_kiosk -->|"reports status"| node_status_ingest
node_heartbeat -.->|"posts heartbeat"| node_status_ingest
node_alpine_heartbeat -.->|"reports status"| node_status_ingest
node_status_ingest -->|"updates state"| node_status_store
node_dashboard -->|"shows status"| node_status_store
node_dashboard -->|"shows health"| node_server_health
node_kiosk -->|"polls actions"| node_action_poll
node_action_poll -->|"returns actions"| node_kiosk
node_operator -->|"manages fleet"| node_dashboard
node_operator -.->|"controls server"| node_server_control
node_operator -->|"edits policy"| node_kiosk_policy
node_kiosk_policy -->|"fetches policy"| node_policy_api
node_policy_api -->|"purges status"| node_status_store
node_doc_manager -->|"manages documents"| node_doc_api
node_doc_api -->|"reads and writes"| node_docs_store
node_doc_preview -->|"reads preview"| node_docs_store
node_operator -.->|"views manuals"| node_manual_viewer
node_manual_viewer -->|"loads manuals"| node_manual_files
node_manual_viewer -.->|"requests preview"| node_doc_preview
node_alpine_setup -.->|"configures device"| node_kiosk
node_installer_report -.->|"installs service"| node_alpine_heartbeat
node_doc_manager -->|"requires session"| node_auth
node_doc_api -->|"checks session"| node_auth
node_server_health -->|"checks session"| node_auth

click node_presentation_app "https://github.com/gotxe/monkiosk/blob/main/kiosk_web/index.php"
click node_content_files "https://github.com/gotxe/monkiosk/tree/main/kiosk_web/docs"
click node_dashboard "https://github.com/gotxe/monkiosk/blob/main/estado_quioscos/index.html"
click node_status_ingest "https://github.com/gotxe/monkiosk/blob/main/estado_quioscos/update_status.php"
click node_status_store "https://github.com/gotxe/monkiosk/blob/main/estado_quioscos/app_config.php"
click node_action_poll "https://github.com/gotxe/monkiosk/blob/main/estado_quioscos/get_action.php"
click node_kiosk_policy "https://github.com/gotxe/monkiosk/blob/main/estado_quioscos/allowed_kiosks.php"
click node_policy_api "https://github.com/gotxe/monkiosk/blob/main/estado_quioscos/allowed_kiosks_api.php"
click node_server_health "https://github.com/gotxe/monkiosk/blob/main/estado_quioscos/server_status.php"
click node_server_control "https://github.com/gotxe/monkiosk/blob/main/estado_quioscos/server_control.php"
click node_auth "https://github.com/gotxe/monkiosk/blob/main/estado_quioscos/auth_lib.php"
click node_doc_manager "https://github.com/gotxe/monkiosk/blob/main/estado_quioscos/docs_manager.php"
click node_doc_api "https://github.com/gotxe/monkiosk/blob/main/estado_quioscos/docs_api.php"
click node_doc_preview "https://github.com/gotxe/monkiosk/blob/main/estado_quioscos/docs_preview.php"
click node_docs_store "https://github.com/gotxe/monkiosk/tree/main/estado_quioscos"
click node_manual_viewer "https://github.com/gotxe/monkiosk/blob/main/kiosk_info/index.php"
click node_manual_files "https://github.com/gotxe/monkiosk/tree/main/kiosk_info/src"
click node_heartbeat "https://github.com/gotxe/monkiosk/blob/main/kiosks_report/debian/report_status.sh"
click node_alpine_heartbeat "https://github.com/gotxe/monkiosk/tree/main/kiosks_report/alpine"
click node_alpine_setup "https://github.com/gotxe/monkiosk/blob/main/Quioscos_install_alpine/setup_quiosco.sh"
click node_installer_report "https://github.com/gotxe/monkiosk/blob/main/Quioscos_install_alpine/install_report.sh"

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_presentation_app,node_content_files toneBlue
class node_dashboard,node_status_ingest,node_status_store,node_action_poll,node_kiosk_policy,node_policy_api,node_server_health,node_server_control,node_auth toneAmber
class node_doc_manager,node_doc_api,node_doc_preview,node_docs_store,node_manual_viewer,node_manual_files toneMint
class node_heartbeat,node_alpine_heartbeat,node_alpine_setup,node_installer_report toneRose
class node_operator,node_kiosk toneIndigo
```

## Components

### Kiosk presentation

- [Content presentation](https://github.com/gotxe/monkiosk/blob/main/kiosk_web/index.php): `kiosk_web/index.php`
- [Presentation files](https://github.com/gotxe/monkiosk/tree/main/kiosk_web/docs): `kiosk_web/docs`

### Monitoring and control

- [Status dashboard](https://github.com/gotxe/monkiosk/blob/main/estado_quioscos/index.html): `estado_quioscos/index.html`
- [Heartbeat intake](https://github.com/gotxe/monkiosk/blob/main/estado_quioscos/update_status.php): `estado_quioscos/update_status.php`
- [Kiosk status state](https://github.com/gotxe/monkiosk/blob/main/estado_quioscos/app_config.php): `estado_quioscos/app_config.php`
- [Pending actions](https://github.com/gotxe/monkiosk/blob/main/estado_quioscos/get_action.php): `estado_quioscos/get_action.php`
- [Kiosk access policy](https://github.com/gotxe/monkiosk/blob/main/estado_quioscos/allowed_kiosks.php): `estado_quioscos/allowed_kiosks.php`
- [Policy API](https://github.com/gotxe/monkiosk/blob/main/estado_quioscos/allowed_kiosks_api.php): `estado_quioscos/allowed_kiosks_api.php`
- [Server health](https://github.com/gotxe/monkiosk/blob/main/estado_quioscos/server_status.php): `estado_quioscos/server_status.php`
- [Server controls](https://github.com/gotxe/monkiosk/blob/main/estado_quioscos/server_control.php): `estado_quioscos/server_control.php`
- [Session authentication](https://github.com/gotxe/monkiosk/blob/main/estado_quioscos/auth_lib.php): `estado_quioscos/auth_lib.php`

### Content and documentation

- [Document manager](https://github.com/gotxe/monkiosk/blob/main/estado_quioscos/docs_manager.php): `estado_quioscos/docs_manager.php`
- [Document API](https://github.com/gotxe/monkiosk/blob/main/estado_quioscos/docs_api.php): `estado_quioscos/docs_api.php`
- [Document preview](https://github.com/gotxe/monkiosk/blob/main/estado_quioscos/docs_preview.php): `estado_quioscos/docs_preview.php`
- [Managed documents](https://github.com/gotxe/monkiosk/tree/main/estado_quioscos): `estado_quioscos`
- [Manual viewer](https://github.com/gotxe/monkiosk/blob/main/kiosk_info/index.php): `kiosk_info/index.php`
- [Manual files](https://github.com/gotxe/monkiosk/tree/main/kiosk_info/src): `kiosk_info/src`

### Kiosk heartbeat and setup

- [Heartbeat reporter](https://github.com/gotxe/monkiosk/blob/main/kiosks_report/debian/report_status.sh): `kiosks_report/debian/report_status.sh`
- [Alpine heartbeat service](https://github.com/gotxe/monkiosk/tree/main/kiosks_report/alpine): `kiosks_report/alpine`
- [Alpine kiosk installer](https://github.com/gotxe/monkiosk/blob/main/Quioscos_install_alpine/setup_quiosco.sh): `Quioscos_install_alpine/setup_quiosco.sh`
- [Reporter installer](https://github.com/gotxe/monkiosk/blob/main/Quioscos_install_alpine/install_report.sh): `Quioscos_install_alpine/install_report.sh`

### Other components

- **Operator**
- **Kiosk device**

## Connections

- Kiosk device → Content presentation: opens content (evidence: `README.md`)
- Content presentation → Presentation files: reads files (evidence: `README.md`)
- Kiosk device → Heartbeat intake: reports status (evidence: `README.md`)
- Heartbeat reporter → Heartbeat intake: posts heartbeat
- Alpine heartbeat service → Heartbeat intake: reports status
- Heartbeat intake → Kiosk status state: updates state (evidence: `estado_quioscos/update_status.php`)
- Status dashboard → Kiosk status state: shows status (evidence: `README.md`)
- Status dashboard → Server health: shows health (evidence: `README.md`)
- Kiosk device → Pending actions: polls actions (evidence: `README.md`)
- Pending actions → Kiosk device: returns actions (evidence: `README.md`)
- Operator → Status dashboard: manages fleet (evidence: `README.md`)
- Operator → Server controls: controls server
- Operator → Kiosk access policy: edits policy (evidence: `estado_quioscos/allowed_kiosks.php`)
- Kiosk access policy → Policy API: fetches policy (evidence: `estado_quioscos/allowed_kiosks.php`)
- Policy API → Kiosk status state: purges status (evidence: `estado_quioscos/allowed_kiosks_api.php`)
- Document manager → Document API: manages documents (evidence: `estado_quioscos/docs_manager.php`)
- Document API → Managed documents: reads and writes (evidence: `estado_quioscos/docs_api.php`)
- Document preview → Managed documents: reads preview (evidence: `estado_quioscos/docs_preview.php`)
- Operator → Manual viewer: views manuals
- Manual viewer → Manual files: loads manuals (evidence: `kiosk_info/index.php`)
- Manual viewer → Document preview: requests preview
- Alpine kiosk installer → Kiosk device: configures device
- Reporter installer → Alpine heartbeat service: installs service
- Document manager → Session authentication: requires session (evidence: `estado_quioscos/docs_manager.php`)
- Document API → Session authentication: checks session (evidence: `estado_quioscos/docs_api.php`)
- Server health → Session authentication: checks session (evidence: `estado_quioscos/server_status.php`)