rnotes-online/MODULE_SPEC.md

# rNotes — Collaborative Notebooks

**Module ID:** `rnotes`
**Domain:** `rnotes.online`
**Version:** 0.1.0
**Framework:** Next.js 14 / React 18 / Prisma / PostgreSQL / TipTap
**Status:** Active

## Purpose

Rich note-taking with notebooks, tags, file uploads, voice transcription, and canvas integration. Supports per-notebook collaboration with role-based access. Notes can embed as shapes on the rSpace canvas.

## Data Model

### Core Entities (Prisma)

| Model | Key Fields | Relationships |
|-------|-----------|---------------|
| **User** | id, did (EncryptID DID), username | has many Notebook, Note, NotebookCollaborator |
| **Notebook** | id, title, slug (unique), description, coverColor, isPublic, canvasSlug, canvasShapeId | has many Note, NotebookCollaborator, SharedAccess |
| **NotebookCollaborator** | userId, notebookId, role (OWNER/EDITOR/VIEWER) | belongs to User, Notebook |
| **Note** | id, title, content, contentPlain, type (enum), url, isPinned, sortOrder, canvasSlug, canvasShapeId | belongs to Notebook, User (author) |
| **Tag** | id, name (unique), color | many-to-many with Note via NoteTag |
| **SharedAccess** | notebookId, sharedByUserId, sharedWithDID, role | cross-user sharing |

### Note Types

NOTE, CLIP, BOOKMARK, CODE, IMAGE, FILE, AUDIO

### Collaborator Roles

OWNER, EDITOR, VIEWER (per-notebook)

## Permission Model

### Space Integration

rNotes currently operates at the notebook level, not the space level. The migration path adds a space-level role that sets the default notebook access.

- **SpaceVisibility:** Mapped to notebook `isPublic` flag (public → true)
- **Default role for open spaces:** PARTICIPANT (can create notebooks and edit own notes)

### Capabilities

| Capability | Required SpaceRole | AuthLevel | Description |
|-----------|-------------------|-----------|-------------|
| `view_notebooks` | VIEWER | BASIC | See notebook list and read notes |
| `create_notebook` | PARTICIPANT | STANDARD | Create new notebooks |
| `edit_own_notes` | PARTICIPANT | STANDARD | Edit/delete own notes in any shared notebook |
| `edit_any_notes` | MODERATOR | STANDARD | Edit/delete any user's notes |
| `manage_notebooks` | ADMIN | ELEVATED | Delete notebooks, manage collaborators |

### Module-Specific Overrides

Per-notebook `CollaboratorRole` overrides the space-level default:
- Space PARTICIPANT + Notebook OWNER → full notebook control
- Space PARTICIPANT + Notebook VIEWER → read-only on that notebook
- Space MODERATOR → EDITOR on all notebooks (override)
- Space ADMIN → OWNER on all notebooks (override)

### Current Auth Implementation

- EncryptID DID from JWT claims
- `getAuthUser(request)` → extracts DID, upserts User
- `requireAuth(request)` → returns 401 if no valid token
- `getNotebookRole(userId, notebookId)` → looks up CollaboratorRole
- First authenticated user auto-claims orphaned notebooks

## API Endpoints

| Method | Path | Auth Required | Capability | Description |
|--------|------|---------------|------------|-------------|
| GET | /api/notebooks | Yes | view_notebooks | List user's notebooks |
| POST | /api/notebooks | Yes | create_notebook | Create notebook |
| GET | /api/notebooks/[id] | Depends | view_notebooks | Get notebook details |
| PUT | /api/notebooks/[id] | Yes | edit_own_notes | Update notebook |
| DELETE | /api/notebooks/[id] | Yes | manage_notebooks | Delete notebook |
| GET | /api/notebooks/[id]/notes | Depends | view_notebooks | List notes |
| GET | /api/notebooks/[id]/canvas | Yes | view_notebooks | Get canvas shape data |
| PUT | /api/notebooks/[id]/canvas | Yes | edit_own_notes | Update canvas binding |
| GET | /api/notes | Yes | view_notebooks | Global notes list |
| POST | /api/notes | Yes | edit_own_notes | Create note |
| GET | /api/notes/[id] | Depends | view_notebooks | Get note |
| PUT | /api/notes/[id] | Yes | edit_own_notes | Update note |
| DELETE | /api/notes/[id] | Yes | edit_own_notes | Delete own note |
| GET | /api/notes/search | Yes | view_notebooks | Full-text search |
| POST | /api/uploads | Yes | edit_own_notes | Upload file |
| GET | /api/uploads/[filename] | Depends | view_notebooks | Download file |
| POST | /api/voice/transcribe | Yes | edit_own_notes | Audio→text |
| POST | /api/voice/diarize | Yes | edit_own_notes | Speaker diarization |

## Canvas Integration

Notes and notebooks embed as shapes on the rSpace canvas:
- **`folk-note`**: Individual note card (title + content preview)
- **`folk-notebook`**: Notebook container showing note count
- Bidirectional binding via `canvasSlug` and `canvasShapeId` fields
- Editing a note shape on canvas updates the note in PostgreSQL
- Creating a note in rNotes can auto-place a shape on canvas

## Cross-Module Dependencies

| Module | Integration |
|--------|------------|
| **rSpace** | Canvas shape embedding (folk-note, folk-notebook) |
| **EncryptID** | DID-based identity and authentication |
| **rFiles** | File attachments referenced in notes |

## Local-First / Offline Support

- Currently server-authoritative (Prisma/PostgreSQL)
- Client state managed with Zustand
- Local-first Transformers.js for on-device AI inference
- Future: TipTap Y.js integration for offline collaborative editing
- Future: IndexedDB cache for offline note access

## Migration Plan

1. Add space concept: link notebooks to a space slug (optional, backwards-compatible)
2. Import `SpaceRole` from SDK for space-level role resolution
3. Add `resolveSpaceRole()` call in `getAuthUser()` or a new middleware layer
4. Cascade space role → default notebook role:
   - Space PARTICIPANT → Notebook EDITOR (on newly accessed notebooks)
   - Space VIEWER → Notebook VIEWER
   - Space MODERATOR → Notebook EDITOR (all notebooks)
   - Space ADMIN → Notebook OWNER (all notebooks)
5. Keep per-notebook `CollaboratorRole` overrides for fine-grained control
6. Replace direct role checks with `hasCapability()` in API route handlers