magdev
da048434b8
README is now tight and link-heavy: 60-second tour, then deep links into docs/. The wall of detail moved out. docs/ covers the framework end-to-end: - getting-started.md — prerequisites by distro (Tumbleweed, Fedora, Debian/Ubuntu, Arch), full first-run walkthrough, troubleshooting. - architecture.md — process pair, transport, dev/bundled mode. - update-semantics.md — state machine + optimistic mutations + key round-tripping. - reactive-models.md — ReactiveListModel, ReactiveObject, Mercure dual-publish. - makers.md — make:bridge:resource/command/window. - dev-workflow.md — hot reload (PHP + QML), dev console, editor configs, bridge:doctor, snapshot/integration test loops, perfsmoke. - bundled-mode.md — supervisor, per-session secret rotation, first-launch migrations, auto-update wiring. - packaging-linux.md — make appimage, build-appimage.sh CLI, AppImageUpdate sidecar, perfsmoke budgets, release CI, bundle-size breakdown. - qml-api.md / php-api.md — exhaustive symbol reference with all Q_PROPERTY/Q_INVOKABLE/signals + every public PHP service / attribute / command. - configuration.md — every env var (host, Symfony, dev script, packaging script, perfsmoke), every CLI flag (php-qml-init, build-appimage.sh), make targets, default ports/paths. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
35 lines
2.2 KiB
Markdown
35 lines
2.2 KiB
Markdown
# Documentation
|
|
|
|
Developer documentation for [php-qml](../README.md). Design rationale and roadmap live in [PLAN.md](../PLAN.md); per-release changes in [CHANGELOG.md](../CHANGELOG.md).
|
|
|
|
## Start here
|
|
|
|
- **[Getting started](getting-started.md)** — install prerequisites, scaffold a project, run it, troubleshoot.
|
|
- **[Architecture](architecture.md)** — process-pair design, transport, dev vs bundled mode.
|
|
|
|
## Concepts
|
|
|
|
- **[Update semantics](update-semantics.md)** — `Connecting → Online → Reconnecting → Offline`, optimistic mutations, idempotency-key round-tripping.
|
|
- **[Reactive models](reactive-models.md)** — `ReactiveListModel`, `ReactiveObject`, Mercure dual-publish on `app://model/<name>` and `app://model/<name>/<id>`.
|
|
- **[Bundled mode](bundled-mode.md)** — what changes when there is no `BRIDGE_URL`: supervisor, per-session secret rotation, first-launch migrations.
|
|
|
|
## Guides
|
|
|
|
- **[Makers](makers.md)** — `make:bridge:resource`, `make:bridge:command`, `make:bridge:window`.
|
|
- **[Dev workflow](dev-workflow.md)** — hot reload (PHP + QML), dev console (`Ctrl+\``), editor configs, `bridge:doctor`.
|
|
- **[Linux packaging](packaging-linux.md)** — `make appimage`, AppImageUpdate, performance budgets.
|
|
|
|
## Reference
|
|
|
|
- **[QML API](qml-api.md)** — `BackendConnection`, `RestClient`, `MercureClient`, `ReactiveListModel`, `ReactiveObject`, `AppShell`, `DevConsole`, `SingleInstance`.
|
|
- **[PHP API](php-api.md)** — `BridgeBundle`, `#[BridgeResource]`, `ModelPublisher`, `bridge:doctor`, `CorrelationKeyListener`, `SessionAuthenticator`.
|
|
- **[Configuration](configuration.md)** — env vars (`BRIDGE_URL`, `BRIDGE_TOKEN`, `FRANKENPHP`, …) and CLI flags for `php-qml-init` / `build-appimage.sh`.
|
|
|
|
## How the docs are organised
|
|
|
|
- **Concept** docs answer *what is this and why?*. They reference code only when it clarifies the model.
|
|
- **Guide** docs walk through a workflow end-to-end with copy-pasteable commands.
|
|
- **Reference** docs are exhaustive lookups for symbols, env vars, and flags. They prioritise findability over narrative.
|
|
|
|
When something is in flux or aspirational, the doc says so and links into [PLAN.md](../PLAN.md). When a feature is shipped, the doc covers it without forward-looking caveats.
|