tapHLEdb — the tapHLE app compatibility database

A small web app for the public tapHLE app compatibility database: where each early iPhone OS app currently stands when run under tapHLE on Windows. It is a live database (humans and coding agents submit results, a moderator approves them), not a file in the emulator repository.

It tracks three kinds of items in a hierarchy:

• Apps — an application tested in tapHLE (identity from its Info.plist).
• Versions — a specific version of an app.
• Reports — a single tester's (or agent's, or telemetry run's) result for a version: a 1–5 star rating plus the Windows host, tapHLE version, and the current frontier.

Ratings and every extra field are defined in config.php (see config.example.php). Ratings follow tapHLE's scale; a coding agent may confirm up to 3 stars, and 4–5 stars require human testing. The database holds structured data only — narrative debugging notes live in the emulator repository under dev-docs/app-notes/.

Provenance and licence

This is a fork of app-compatibility-db by hikari_no_yume, the web app that also powers touchHLE's app database.

Copyright © 2023 hikari_no_yume, and © 2026 the tapHLE contributors for modifications. All the code here is licensed under MPL-2.0. All HTML and CSS that the app can output is additionally licensed under CC0-1.0 so databases produced with it can be freely archived and redistributed. Submitted database content is under CC BY 4.0 (see SITE_CONTENT_LICENSE_* in the config).

tapHLE's own compatibility ratings are always produced by a tapHLE run; touchHLE or HyperHLE results are testing leads only and are never imported as ratings.

What tapHLE changed from upstream

• config.example.php: tapHLE branding, tapHLE's 1–5 rating scale, and the fields — app bundle_identifier/developer, version bundle_version/min-OS, and report source_type (human/agent/telemetry), taphle_version, and frontier.
• A small JSON API so tapHLE telemetry and coding agents can work with the database without the interactive GitHub sign-in: POST /api/report submits a result (token-authenticated, always landing unapproved for moderator review), and GET /api/apps reads the public list so an agent can choose what to work on. See API.md. The code is confined to include/api.php and the two templates/api_*.phpt files plus two routes in htdocs/index.php, to keep the diff against upstream small.
• printExternalUsername() in include/util.php only links to GitHub for a github: identity. API identities such as telemetry:taphle have no profile page, so linking them would point at a GitHub account that does not exist.

Pull upstream fixes with the upstream remote: git fetch upstream && git log --oneline HEAD..upstream/main.

Setting up

Requires git, PHP 7.4/8, and the SQLite 3 CLI.

1. cp config.example.php config.php, then edit config.php: fill the GitHub OAuth keys and any API tokens (keep them secret — config.php is git-ignored).
2. Create the database: sqlite3 app_db.sqlite3 '.read schema.sql'
3. Serve locally: cd htdocs && php -S localhost:8000

Deployment

Use the example nginx + PHP-FPM config. The app can serve from a domain root or from a subpath — set SITE_BASE_PATH in config.php (the tapHLE deployment uses /compatibility) and register the GitHub OAuth callback at the matching URL.

The SQLite database file and the directory containing it must be writeable by the web server: SQLite creates journal files alongside the database, so a writeable file in a read-only directory fails on every write.

Unlike upstream, htdocs/privacy.html is committed rather than git-ignored. This is a single deployment, so version-controlling the policy keeps it reviewable and means a deploy is just a pull. Upstream ignores it because each operator needs their own; anyone forking this repo should replace it. It still carries bracketed placeholders (contact, jurisdiction, retention periods) that must be filled in before it is truthful.

Source layout

• schema.sql: SQL schema (apps, versions, reports, screenshots, users)
• config.example.php: configuration example/documentation
• API.md: the programmatic API — GET /api/apps, POST /api/report
• privacy.example.html: example privacy policy
• nginx-config-example.conf: example nginx config
• htdocs/index.php: sole entry point and router
• templates/: templates and view/controller code
• include/: utility functions and model code