{
  "markdown": "# EweserDB\n\nEweserDB is a local-first, user-owned database SDK built on Yjs CRDTs. Users own their data, and apps interoperate over shared schemas.\n\n## Self-Hosting\n\n**One-click deploy on Railway**:\n\n[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/JPbli2?referralCode=WlO5hM&utm_medium=integration&utm_source=template&utm_campaign=generic)\n\n**Self-host on any VPS**:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/eweser/eweser-db/main/scripts/setup-vps.sh | bash\n```\n\n[Full deployment guides](docs/deployment/)\n\n## What It Includes\n\n- `@eweser/db` - core JavaScript client for local-first rooms and documents\n- `@eweser/shared` - shared types, schemas, and helpers\n- `@eweser/auth-server-hono` - Hono + better-auth auth API\n- `@eweser/app` - React SPA for login, signup, account management, and access grants\n- `@eweser/aggregator` - server-side indexing and public search\n- `@eweser/sync-server` - Hocuspocus sync relay\n- `@eweser/mcp` - MCP tools for authorized agent access to scoped rooms\n- `@eweser/ewe-note` - TipTap-based Obsidian-compatible note-taking app\n- example apps under `examples/`\n\n## Quick Start\n\n```bash\nnpm install @eweser/db yjs\n```\n\nThis is a simplified example. For more complete usage, see the example apps in `examples/`.\n\n```tsx\nimport { Database } from '@eweser/db';\nimport type { Note } from '@eweser/db';\n\nconst initialRooms = [\n  {\n    collectionKey: 'notes',\n    name: 'My Notes on Life and Things',\n  },\n];\n\nconst db = new Database({ initialRooms });\n\ndb.on('roomsLoaded', () => {\n  // Ready to use in offline mode immediately.\n});\n\nconst notesRoom = db.getRoom<Note>('notes', 'my-notes-on-life-and-things');\n\n// This wrapper exposes CRDT-safe document helpers for the room.\nconst Notes = db.getDocuments(notesRoom);\n\nNotes.onChange((event) => {\n  console.log('ydoc changed', event);\n});\n\nNotes.new({ text: 'hello world' });\n\n// To enable remote sync, connect through the auth API and sync relay.\nconst loginUrl = db.generateLoginUrl({ name: 'Basic Example App' });\n\nif (db.getToken()) {\n  db.login();\n}\n```\n\nThat is enough to get a local-first database. It remains usable offline and can\nsync between devices and apps when remote sync is connected.\n\n## Core Ideas\n\n### Rooms\n\nA room is a Yjs-backed container with a collection key, shared schema, and room\naccess control. Rooms are the main authorization and remote-sync boundary.\nFolders and bases can organize room content, but they do not replace room\ncollection boundaries.\n\n### Collections and Schemas\n\nCollections define strongly typed document shapes. Apps that share a schema can interoperate on the same data.\n\n### Remote Sync\n\nApps load local IndexedDB-backed Yjs state first. Remote sync is optional and\nuses the Hocuspocus sync relay with short-lived sync tokens for scoped room\nconnections. Synced does not mean public.\n\n### References\n\nDocuments can be linked by reference using `_ref` values in the form:\n\n`${authServer}|${collectionKey}|${roomId}|${documentId}`\n\nUse `buildRef()` from `@eweser/shared` to construct refs.\n\n### Access Control\n\nThe auth API owns room ACLs, access grants, sessions, and sync-token issuance.\nRoom ACLs define owner/admin/read/write rights. Access grants authorize an app\nor agent for selected rooms and capabilities. Sync tokens authorize a specific\nremote-sync connection.\n\n### Public Aggregation\n\nThe aggregator indexes explicitly public rooms for public search. Public search\nis separate from ordinary remote sync, collaborator sharing, and MCP-readable\nagent access.\n\n### User Snapshots\n\nA user snapshot is a portable backup bundle for selected rooms. It is not a\nsync replica, operator database backup, sync relay persistence store, or\nfederation backup listener.\n\n### Encrypted Rooms\n\nOrdinary hosted remote sync is not end-to-end encrypted. Encrypted rooms are an\nopt-in room-level capability being planned for sensitive data, with explicit\ntradeoffs for public search, MCP access, recovery, and collaboration.\n\n### MCP and Agent Access\n\nMCP tools expose only rooms included in an agent's readable or writable room\nscope. MCP-readable rooms are not public-searchable unless the room is also\nexplicitly public.\n\n## Example Apps\n\n### Landing\n\n- Dev URL: `http://localhost:4000/`\n- Source: `packages/landing`\n\n### Kitchen Sink (All Features)\n\n- Dev URL: `http://localhost:38110/`\n- Source: `examples/example-basic`\n- Demonstrates multi-room notes, flashcards, profiles, cross-collection linking, sharing, room rename, connection status, auth flow, and offline-first loading\n\n### Multi-Room Notes\n\n- Dev URL: `http://localhost:38120/`\n- Source: `examples/example-multi-room`\n\n### Interop Notes + Flashcards\n\n- Notes app: `http://localhost:38130/`\n- Flashcards app: `http://localhost:38140/`\n- Source: `examples/example-interop-notes` and `examples/example-interop-flashcards`\n\n## Development\n\n```bash\nnpm install\nnpm run dev:docker\n```\n\n`npm run dev:docker` starts the backend services from `docker-compose.dev.yml`.\n\nFor all apps in one shot (recommended when using VS Code), prepare local ports\nand start the backend:\n\n```bash\ncp -n .worktree-ports.example .worktree-ports\nsource .worktree-ports 2>/dev/null || true\nnpm run dev:docker\n```\n\nIf this checkout was created with `ewtnew`, `.worktree-ports` is generated for\nthe worktree automatically by `scripts/worktree-env.mjs`.\n\nThen in VS Code: `Tasks: Run Task` → `Run All Dev`.\n\nThat task starts:\n\n- Docker backend\n- DB dev server\n- Shared package dev server\n- Landing page\n- App SPA\n- Example basic, multi-room, interop notes, and interop flashcards\n- Examples components watcher\n- Ewe Note\n\nIf you are not in VS Code, start these in separate terminals:\n\n```bash\nnpm run dev --workspace @eweser/db\nnpm run dev --workspace @eweser/shared\ncd packages/landing && npm run dev -- --host 127.0.0.1 --port \"${LANDING_PORT:-4000}\" --strictPort\ncd packages/app && npm run dev -- --host 127.0.0.1 --port \"${AUTH_PAGES_PORT:-${APP_PORT:-3001}}\" --strictPort\ncd examples/example-basic && npm run dev -- --host 127.0.0.1 --port \"${EXAMPLE_BASIC_PORT:-38110}\" --strictPort\ncd examples/example-multi-room && npm run dev -- --host 127.0.0.1 --port \"${EXAMPLE_MULTI_ROOM_PORT:-38120}\" --strictPort\ncd examples/example-interop-notes && npm run dev -- --host 127.0.0.1 --port \"${EXAMPLE_INTEROP_NOTES_PORT:-38130}\" --strictPort\ncd examples/example-interop-flashcards && npm run dev -- --host 127.0.0.1 --port \"${EXAMPLE_INTEROP_FLASHCARDS_PORT:-38140}\" --strictPort\ncd packages/ewe-note && npm run dev -- --host 127.0.0.1 --port \"${EWE_NOTE_PORT:-5181}\" --strictPort\n```\n\n`npm run dev` covers shared package + example packages, but not landing or app, so use the full command list above when you need every app.\n\n- Landing page: `http://localhost:4000/`\n- Auth API health: `http://localhost:38101/health`\n- Auth pages dev server: `http://localhost:3001/auth/`\n- Example basic app: `http://localhost:38110/`\n- Multi-room app: `http://localhost:38120/`\n- Notes interop: `http://localhost:38130/`\n- Flashcards interop: `http://localhost:38140/`\n- Ewe Note dev server: `http://localhost:5181/`\n\nRun unit tests with `npm run test`.\nRun e2e tests with `npm run test:e2e` or `npm run dev-e2e` for the Cypress UI.\n\n## Quality and Contributing\n\nAll code must pass linting, formatting, type-checking, and tests before merging:\n\n```bash\nnpm run check\n```\n\nAny change to a published package requires a changeset:\n\n```bash\nnpm run changeset\n```\n\n## Notes\n\n- Users should be told which room scopes and capabilities an app or agent is\n  being granted for the duration of the session.\n- Historical migration notes are kept in `docs/ai/` and `docs/ai/adr/`.\n- Keep the docs in this repository aligned with the current package layout and workspace scripts.\n",
  "bytes": 7748,
  "sha": "5a527aaf06757b4495f51024b74caf92f9a43108535d1392c3300e82381dd52c",
  "repo_slug": "eweser/eweser-db",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_eweser_eweser_db_packages_ewe_note_test__458f67d5/readme"
}