mirror of
https://github.com/Shik3i/KoalaSync.git
synced 2026-08-22 17:06:36 +00:00
Timo
60 lines
3.1 KiB
Markdown
60 lines
3.1 KiB
Markdown
# KoalaSync AI Onboarding (AI_INIT.md)
|
||
|
||
Welcome to the KoalaSync project. This file is the primary entry point for any developer or AI agent working on this codebase. It defines the architecture, non-negotiables, and workflows required to maintain the stability and security of the system.
|
||
|
||
> [!IMPORTANT]
|
||
> **Privacy & Data Sovereignty**: KoalaSync follows a strict **Zero-External-Requests Policy**: The extension and website must not make requests to any third-party domains. All assets must be self-hosted.
|
||
> - **Font Stack**: Use a modern system font stack to maintain a premium look without external dependencies.
|
||
|
||
---
|
||
|
||
## 1. Project Overview
|
||
KoalaSync is a specialized tool for **synchronized video playback** across multiple remote peers.
|
||
- **Workflow**: A user creates a room, shares an invitation link, and all peers are synchronized via a Node.js relay server.
|
||
- **Identity**: Users are identified by a unique hex `peerId` combined with a customizable `username`.
|
||
|
||
## 2. Repository Structure
|
||
- `extension/`: Chrome Extension (Manifest V3).
|
||
- `server/`: Node.js Relay Server using Socket.IO (WebSocket-only).
|
||
- `website/`: Landing Page & Invitation Bridge.
|
||
- `shared/`: Single Source of Truth for protocol constants and event names.
|
||
|
||
## 3. Mandatory Reading
|
||
1. [ARCHITECTURE.md](ARCHITECTURE.md) – Communication flows and Dual Heartbeat protocol.
|
||
2. [extension/README.md](extension/README.md) – UI structure and component overview.
|
||
|
||
## 4. Design Guidelines
|
||
- **Popup Width**: Fixed at `320px`.
|
||
- **Tab Structure**: **Room**, **Sync**, **Settings**, and **Dev**.
|
||
- **CSS Variables**: Uses the CSS variables defined in `popup.html` for a consistent Dark Mode / Glassmorphic look.
|
||
|
||
## 5. Non-Negotiables (Core Logic)
|
||
- **Two-Phase Force Sync**: `Prepare` → `ACK` → `Execute` flow for frame-perfect sync.
|
||
- **Dual Heartbeat**:
|
||
- **Background Heartbeat (30s)**: Keeps the session alive even without a video.
|
||
- **Content Heartbeat (15s)**: Transmits current video metadata (title, time).
|
||
- **Dead Peer Pruning**: Server automatically disconnects peers after 5 minutes of total silence.
|
||
- **Deduplication**: Server kills old sockets if a user re-joins with the same `peerId`.
|
||
- **Diagnostics**: The "Dev" tab provides real-time access to the underlying `<video>` state for troubleshooting.
|
||
|
||
## 6. Technical Constraints
|
||
- **No Bundler**: Plain ES Modules only.
|
||
- **Socket.IO Protocol**: Manual implementation of the wire protocol in `background.js`.
|
||
- **Docker Context**: Must build from the **Repo Root**.
|
||
|
||
## 7. Security & Deployment
|
||
- **Invitation Links**: Correctly propagate server URLs and room credentials via the URL hash.
|
||
- **Rate Limiting**: IP and socket-based limits are enforced server-side.
|
||
- **Persistence**: `peerId` and `username` must persist across browser sessions.
|
||
|
||
## 8. Common Workflows
|
||
|
||
### Modifying the Protocol
|
||
1. Edit `shared/constants.js`.
|
||
2. Run `scripts/sync-constants.bat` (Windows) or `scripts/sync-constants.sh` (POSIX).
|
||
3. Restart the server and reload the extension.
|
||
|
||
### Testing
|
||
- Use **different browser profiles** or vendors to test multi-peer logic locally.
|
||
- Use the **Dev tab** to verify that the extension is correctly detecting the video state.
|