One shared contract
Zod schemas and permission rules live in @musubi/types, imported by both
the Express server and the Expo client.
Musubi documentation
From first boot to confident contribution — architecture, workflows, provider sync, API reference, and production operations.
Choose your path
Section titled “Choose your path”I am new to the codebaseA guided, source-driven course: run Musubi, learn its core model, trace a request, and make a safe first change.
I want to contributeBranching, verification, database migrations, project conventions, and the pull-request checklist.
I operate a Musubi serverDocker Compose, secrets, HTTPS, updates, backups, recovery drills, metrics, logs, and alerts.
I am integrating with the APIAuthentication, public routes, endpoint inventory, response conventions, realtime events, and source locations.
The idea everything else builds on
Section titled “The idea everything else builds on”Musubi (結び, knot or bond) is an open, self-hostable shared calendar. Its data model deliberately differs from most calendar systems:
An event is not nested inside one calendar. It is linked into one or more calendars.
The events table has no calendarId. calendar_events links one event to
many calendars, while events.originCalendarID identifies the home calendar
whose role controls editing. Once this is clear, permissions, link vs fork,
external mirrors, federation, realtime updates, and the client cache all become
much easier to reason about.
Offline-tolerant client
Zustand is the live state; SQLite is the local mirror; delta sync is the durable reconciliation path; SSE makes changes feel immediate.
Provider-agnostic sync
Google, Microsoft, and CalDAV adapters normalize calendars and events behind
one CalendarAdapter contract.
Self-hostable operations
One Node API and PostgreSQL database, with migrations on boot, JSON logs, Prometheus metrics, dashboards, alerts, and tested backup scripts.
Fast reference
Section titled “Fast reference”| Need | Go to |
|---|---|
| Start every workspace | Run locally |
| Find the right file | Architecture overview |
| Understand a project term | Glossary |
| Look up a command | Commands & checks |
| Configure the server | Environment variables |
| Add or debug an endpoint | API server and HTTP API reference |
| Add a sync provider | Sync engine |
| Review known risks | Codebase audit |