# Sideloom

**Repository Path**: foenic/sideloom

## Basic Information

- **Project Name**: Sideloom
- **Description**: 多端协同看板系统设计方案
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-05-26
- **Last Updated**: 2026-06-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Sideloom

A multi-device collaborative kanban system: turn spare phones or tablets into secondary displays, deeply integrated with Obsidian and similar tools for a local-first **edit on desktop → show on display** workflow.

> **Project status**: This repository currently holds **domain design, protocol specs, and OpenSpec change proposals**. There is no installable `package.json` or application source yet. The [Quick start](#quick-start) section describes how to read and contribute to the design; run/deploy instructions will be added when implementation lands.

[中文](./README.md)

---

## Features (planned)

| Capability | Description |
|------------|-------------|
| Local Core service | Runs on the user’s main machine: pairing, kanban engine, delivery state machine, API gateway |
| Unified adapters | Obsidian plugin, MCP server, CLI, and web admin all talk to the same REST / WebSocket APIs |
| Display ≠ Kanban | Displays and content objects are decoupled; routing via subscriptions (multi-screen, rotation) |
| Domain events | Entry-agnostic names (`kanban.updated`, `delivery.succeeded`); provenance in Envelope `source.type` |
| MVP loop | Pair → WebSocket connect → push → ACK → delivery confirmed |

See [`doc/tech-stack.md`](./doc/tech-stack.md) and [`doc/implementation-roadmap.md`](./doc/implementation-roadmap.md) for stack choices and phased delivery.

---

## Architecture (high level)

```text
                    ┌─────────────────────────────────────┐
                    │         Sideloom Core (local)        │
                    │  REST · WebSocket · Delivery · SQLite│
                    └──────────────┬──────────────────────┘
           ┌───────────────────────┼───────────────────────┐
           │                       │                       │
    ┌──────▼──────┐         ┌──────▼──────┐         ┌──────▼──────┐
    │  Adapter    │         │  Adapter    │         │   Display   │
    │  Obsidian   │         │  MCP / CLI  │         │  Web / PWA  │
    │  (producer) │         │             │         │             │
    └─────────────┘         └─────────────┘         └─────────────┘
```

Full product narrative: [Sideloom - 多端协同看板系统设计方案.md](./Sideloom%20-%20多端协同看板系统设计方案.md) (Chinese).

---

## Repository layout

```text
sideloom/
├── doc/                    # Domain design, events, protocol, roadmap
├── openspec/               # OpenSpec proposals (proposal / design / specs / tasks)
│   ├── project.md
│   └── changes/
├── Sideloom - 多端协同看板系统设计方案.md
├── README.md
└── README.en.md
```

**Doc index**: [`doc/README.md`](./doc/README.md)

---

## Quick start

### Requirements (planned)

- **Node.js** ≥ 20
- **pnpm** (monorepo with `@sideloom/shared`)
- Optional: **Obsidian** for plugin adapter development

Exact versions will be defined in the first committed `package.json`.

### Today: read and align on specs

```bash
git clone https://gitee.com/foenic/sideloom.git
cd sideloom
```

1. Start at [`doc/README.md`](./doc/README.md).
2. Read [`openspec/project.md`](./openspec/project.md) and change proposals under `openspec/changes/`.
3. Optional: experimental OpenSpec skills under `.claude/skills/openspec-*`.

### After implementation (preview)

Target monorepo layout is documented in [`doc/tech-stack.md`](./doc/tech-stack.md) (`packages/shared`, `core`, `display-web`, `web`, `plugin`, `mcp-server`, `cli`). Install and dev commands will be documented here once code exists.

---

## Usage (design phase)

Until runnable code is available:

1. Align on domain terms: Display vs Kanban, `DisplaySubscription` routing ([domain-model.md](./doc/domain-model.md)).
2. Use MVP acceptance criteria in [implementation-roadmap.md](./doc/implementation-roadmap.md) (e.g. `curl` + WS client for pair → push → ack).
3. Track work via OpenSpec `tasks.md` under each `openspec/changes/<id>/`.

---

## Roadmap (summary)

| Phase | Goal |
|-------|------|
| 1 | Shared contracts (`@sideloom/shared`) |
| 2 | Core MVP: REST + WebSocket + delivery |
| 3 | Display MVP (Web/PWA first) |
| 4 | Adapter MVP (Obsidian / CLI, MCP) |
| 5 | SQLite persistence and snapshot recovery |
| 6 | Multi-kanban subscriptions and web admin |

Details: [`doc/implementation-roadmap.md`](./doc/implementation-roadmap.md).

---

## Contributing

1. **Fork** and branch from the default branch (`feat/...`, `docs/...`, `spec/...`).
2. Prefer updating `doc/` or `openspec/changes/<change-id>/` for design changes; keep [protocol.md](./doc/protocol.md) in sync.
3. Write clear commit messages (why, not only what).
4. Open a **Pull Request** with scope, spec impact, and how to verify.

**Guidelines**

- Do not prefix domain events with `plugin:` or `mobile:`; use `source.type` / `Client.kind`.
- Update `doc/protocol.md` and relevant OpenSpec specs when adding REST/WS payloads.
- Do not commit secrets, `.env`, or local tooling artifacts (`.omc/`, `.specstory/`) unless intentionally shared.

---

## Links

| Resource | Path |
|----------|------|
| Design index | [doc/README.md](./doc/README.md) |
| OpenSpec overview | [openspec/project.md](./openspec/project.md) |
| Product design (root) | [Sideloom - 多端协同看板系统设计方案.md](./Sideloom%20-%20多端协同看板系统设计方案.md) |

---

## License

No `LICENSE` file yet. Confirm licensing with maintainers before redistributing; a license file will be linked here when added.