Architecture
Architecture
Internal design documents covering the architecture, key decisions, and internals of labelsync.
For how to drive the tool, see Usage.
These pages describe what has been built. The forward-looking plan — goals, prior art, the reconciliation algorithm, milestones, and open questions — lives in design.md. As each subsystem lands, its behaviour moves from the design plan into this section.
| Page | Covers |
|---|---|
| Overview | Package structure, CLI command tree, the reconciliation data flow |
| Error Handling | Sentinel errors, the %w wrapping rule, and the error_kind JSON contract |
| Output & Exit Codes | output.Writer, pretty vs NDJSON, TTY detection, the slog boundary, exit codes |
| Versioning | The linker-injected Version, and what each build produces |
| Colour Palette | The deterministic HSL candidate grid, its legibility bounds, and determinism |
| Configuration | Config file resolution, YAML parsing, and the normalisation rules |
| Planner | The Action / Plan vocabulary and its JSON contract |
| Authentication | The four-step token resolution chain, and why tokens are redacted at the type |
| GitHub Client | The go-github wrapper, the per-repository error taxonomy, and the 5xx retry |
| Rate Limiting | The write bucket, header tracking, backoff, and the --max-wait ceiling |
| Apply | Executing a plan in append mode, partial runs, and the startup budget check |
| Distribution | The release pipeline, the three install channels, and the Homebrew cask |
| Library Decisions | Every direct dependency, what it is for, and what it was chosen over |
| Demo Recording | The VHS tape behind the GIF, and how to re-record it |
Pages are added here as the subsystems they document are implemented.