wehub-resource-sync
3e779be6f3
CI / lint (push) Failing after 13m4s
CI / test (3.11, ubuntu-latest) (push) Failing after 2m4s
CI / test (3.13, ubuntu-latest) (push) Successful in 13m30s
CI / test (3.14, ubuntu-latest) (push) Successful in 17m21s
CI / test (3.12, ubuntu-latest) (push) Successful in 17m55s
CI / discover-apps-ps (push) Successful in 1m56s
CI / test (3.9, ubuntu-latest) (push) Successful in 13m17s
CI / test (3.10, ubuntu-latest) (push) Successful in 26m21s
CI / audit (push) Successful in 13m38s
Deploy site / deploy (push) Has been cancelled
CI / test (3.14, ubuntu-24.04-arm) (push) Has been cancelled
43 lines
3.3 KiB
Markdown
43 lines
3.3 KiB
Markdown
# docs/design/
|
|
|
|
Engineering-internal documentation: design specs, reference docs, roadmaps, security reviews, and machine-readable schemas. Intended audience is contributors and maintainers, not end users — user-facing docs live one level up in [`../`](../) (see [`../README.md`](../README.md)).
|
|
|
|
A document belongs here when any of these are true:
|
|
- It describes how the code is structured or sequenced (rather than how to use the product).
|
|
- It refers to specific files, functions, or commit-level decisions.
|
|
- It records a decision (review, audit, ADR) made at a point in time.
|
|
- It is consumed by tooling, not humans (schemas, machine-readable specs).
|
|
|
|
## Index
|
|
|
|
### Design specs (`*_DESIGN.md`)
|
|
Proposals and rationale for major subsystems. Each documents the problem, the chosen design, and the trade-offs considered.
|
|
- [AGENT_V2_DESIGN.md](AGENT_V2_DESIGN.md) — host-side HTTP client + guest `agent.ps1` listener (the `/health`, `/exec`, `/events`, `/apply`, `/discover` channel).
|
|
- [AGENT_FIRST_INSTALL_DESIGN.md](AGENT_FIRST_INSTALL_DESIGN.md) — install-time agent bring-up, OEM bind mount, first-boot ordering.
|
|
- [GUEST_SYNC_DESIGN.md](GUEST_SYNC_DESIGN.md) — version-stamp comparison + windowless agent transport for upgrading the guest payload.
|
|
- [REVERSE_OPEN_DESIGN.md](REVERSE_OPEN_DESIGN.md) — Linux "Open with" → Windows handler reverse path (#48).
|
|
|
|
### Reference (process / interface)
|
|
Long-form references that describe code paths or interface contracts.
|
|
- [LIFECYCLE.md](LIFECYCLE.md) ([한국어](LIFECYCLE.ko.md)) — end-to-end pod lifecycle: install, sysprep, migrate, apply chain, multi-session, discovery, transport selection. "Who fires it, what it does, where the code lives."
|
|
- [TRANSPORT_ABC.md](TRANSPORT_ABC.md) — host→guest `Transport` abstract base class, the `FreerdpTransport` / `AgentTransport` contracts, dispatch policy.
|
|
|
|
### Roadmaps
|
|
Per-release cut-lists with execution order and deferred-item tracking.
|
|
- [ROADMAP-0.6.0.md](ROADMAP-0.6.0.md) — Consolidation & UX release: unify provisioning, thin AppImage, command-taxonomy reorg.
|
|
|
|
### Reviews / audits
|
|
Point-in-time decisions and their rationale.
|
|
- [ROTATION_SECURITY_REVIEW_2026-05-07.md](ROTATION_SECURITY_REVIEW_2026-05-07.md) — security review of the password-rotation flow.
|
|
|
|
### Schemas
|
|
Machine-readable specs consumed by tooling.
|
|
- [install_failure.schema.json](install_failure.schema.json) — JSON Schema for the install-failure telemetry blob.
|
|
|
|
## Conventions
|
|
|
|
- **Naming:** design proposals carry the `_DESIGN.md` suffix. Reference / interface / roadmap / review / schema files use a descriptive name without the suffix (their content type is documented by the section they live under here).
|
|
- **Dating:** reviews and audits include the date in the filename (`*_YYYY-MM-DD.md`). Roadmaps include the target version (`ROADMAP-X.Y.Z.md`).
|
|
- **No `.ko.md` mirrors required.** Korean mirrors are for user-facing docs only; engineering docs are English-only unless a specific doc is dual-authored (LIFECYCLE is currently the only exception).
|
|
- **No behaviour-change content.** A design doc describing a change shouldn't ship in the same PR as the change itself land; either the design comes first (the PR that lands the change refers back to it) or the doc is co-authored with the change but marked clearly as describing what just landed.
|