mirror of
https://github.com/Shik3i/KoalaSync.git
synced 2026-08-18 15:23:13 +00:00
Timo
5711daefd4
A peer can be left paused at the end of an episode while the other moves on, and nothing recovers it. The episode guard, the title on the wire and the comparison all exist already, so the interesting part is why the guard lets that one pause through — and that cannot be settled without logs from both sides while it happens. Records what was verified from the code, the three candidate causes that are still hypotheses, the exact log lines that separate them, the planned fix order, and the approaches already ruled out (forcing the comparison would break every platform that exposes no media title). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Technical Documentation
This directory contains deep-dives into the KoalaSync protocol, architecture, roadmap, and operational guidelines.
Start Here by Role
- Users and reviewers: Start with HOW_IT_WORKS.md, then PRIVACY.md and TESTED_SERVICES.md.
- Self-hosters: Start with the root README.md, then devops.md, PROTOCOL.md, and the examples in
../examples/. - Contributors: Start with ../CONTRIBUTING.md, then ARCHITECTURE.md, SYNC_GUIDE.md, and the README for the subdirectory you are editing.
- AI agents: Start with AI_INIT.md, then read the relevant subdirectory README before changing files.
- Security reviewers: Start with SECURITY.md, KNOWN_LIMITATIONS.md, PRIVACY.md, and PROTOCOL.md.
🏗️ Core Architecture & Design
- ARCHITECTURE.md: Overview of the communication flows, Dual Heartbeat architecture, and synchronization logic.
- HOW_IT_WORKS.md: Step-by-step walkthrough of every user flow, from room creation to synchronized playback. Ideal for store reviewers and manual testers.
- host-control-mode.md: Design, requirements, and edge cases of the Host Control feature.
- AI_INIT.md: Maintainer and AI-agent onboarding: non-negotiables, workflow order, and safety checks.
📡 Protocol & Synchronization
- PROTOCOL.md: Low-level message format and payload descriptions for the KoalaSync sync protocol.
- SYNC_GUIDE.md: Guide on keeping protocol constants synchronized across the workspace.
📋 Compatibility, Roadmap & Contribution
- TESTED_SERVICES.md: Status of compatibility with major streaming services and contribution guidelines for testing new platforms.
- KNOWN_LIMITATIONS.md: Threat model and accepted design limitations (NOFIX entries) for security audits.
- PRIVACY.md: Privacy model and data-handling policy for users, reviewers, and contributors.
- ROADMAP.md: Planned features, backlog items, and rejected proposals.
- TRANSLATION.md: Guide for native speakers to contribute and audit dynamic extension/website translations.
🚀 DevOps & Releases
- devops.md: Guide on the automated tag-based release pipeline.
- CHANGELOG.md: Detailed history of releases and changes.
For high-level project information and developer setup instructions, refer to the root README.md.