# Reference

Technical reference for YotoShelf — covering the HTTP API, the go-yoto client library, hardware constraints, upstream API findings, and the architectural decisions behind the project.

## Sections

- [API (OpenAPI)](/reference/api) — Full HTTP endpoint reference generated from the application source via huma. Grouped by tag with method, path, summary, and auth requirement. Includes regeneration instructions.
- [go-yoto Client](/reference/go-yoto) — Package overview, installation, authentication flows, full API coverage table (26 of 27 upstream endpoints), known API quirks, and the weekly live-validation smoke test workflow.
- [Hardware Constraints](/reference/hardware) — Yoto device specifications relevant to card making: cover image dimensions, LED display format, audio pipeline, device types, and label printing templates.
- [Yoto API Findings](/reference/yoto-api-findings) — Verified findings from direct exploration of the Yoto upstream API: endpoint behaviour, undocumented quirks (device status in config, single-use refresh tokens, userinfo scope), MYO card structure, and import feasibility.
- [Architecture](/reference/architecture) — Runtime stack, auth architecture (dual OAuth2 flows, BFF pattern), data model, Go package layout, frontend architecture, and container build.
- [Design Decisions](/reference/decisions) — Rationale behind key choices: local + OIDC auth, collections-centric model, SQLite as source of truth, cover vs label terminology, audio pipeline strategy, federation posture, and more.