Space management and membership
A Space is an instance-level collaboration context for users and their memos. It gives members a shared place to browse, create, and discuss content while keeping memo authorship, memo audience, and user-global areas separate. This page complements memo lifecycle and collaboration with the rules for creating, joining, selecting, and governing Spaces. See also memo query filtering, markdown content processing, and memo archive import and export for related memo flows.
Space model
Space resources
A Space has an immutable resource identity and editable descriptive data. Its resource name uses the form spaces/{space-id}. A Space can also have an optional display icon. The response includes the caller's role and the count of accepted active members when the caller has membership.
Space icons use either one fully qualified emoji or a lower-case Lucide icon name. A nil icon means that the client can use the default Space mark. The web client uses the same Space identity in creation, settings, invitations, and Space selectors. Only an administrator can change the title, description, or icon.
Spaces are flat collaboration contexts. They are not tenants, folders, or nested work areas. A Space does not own a memo or change its author. A memo has either no Space placement or placement in exactly one Space.
References: docs/…/multi-spaces.md• L63-73 proto/…/space_service.proto• L134-160 server/…/space_service_converters.go• L21-69 store/space.go• L67-76 store/space_icon.go• L9-23 store/custom_icon.go• L11-32 web/…/SpaceMark.tsx• L20-30
Resource hierarchy
The API models memberships and invitations as child resources of a Space. This hierarchy groups administration requests under a Space without creating a hierarchy between Spaces.
| Resource | Name pattern | Meaning |
|---|---|---|
| Space | spaces/{space-id} | A collaboration context |
| Membership | spaces/{space-id}/members/{username} | An accepted member and role |
| Invitation | spaces/{space-id}/invitations/{username} | A pending offer to join |
The user invitation list is a separate user-scoped collection. It lets an invitee find pending offers without granting access to the Space itself.
References: proto/…/space_service.proto• L162-215 proto/…/space_service.proto• L295-312 server/…/space_service_converters.go• L9-19
Membership and invitations
Membership states and roles
Membership is an accepted relationship between one active user and one Space. The relationship has one of two roles: ADMIN, which governs the Space, or USER, which participates in it. A pending invitation is not membership and does not grant Space access.
The first administrator is added in the same operation as Space creation. Every later membership comes from an accepted invitation. The system rejects a change that would leave a Space without an active administrator.
| Relationship | Access |
|---|---|
| Pending invitation | Only the invitee can accept or decline it; an administrator can revoke it |
Active USER membership | Browse the Space, use its feed, and participate in assigned content |
Active ADMIN membership | All member access plus Space metadata, invitation, role, removal, and deletion control |
Application-wide administrator status does not bypass Space membership. A user must belong to the Space to read its member-only resources.
References: store/space.go• L36-66 server/…/space_service.go• L30-58 server/…/space_service_test.go• L77-126
Invitation flow
An administrator invites an existing active Memos user and selects the role that will apply after acceptance. The invitee sees a read-only Space summary with the offer. The summary contains Space metadata but does not expose active membership fields. The invitee must explicitly accept to become a member.
The invitation lifecycle follows this sequence:
sequenceDiagram
actor Admin
actor Invitee
participant API
participant Space
participant Inbox
Admin->>API: Create invitation with invitee and role
API->>Space: Store pending invitation
API->>Inbox: Add invitation notification
Space-->>Invitee: Show Space summary and offered role
alt Invitee accepts
Invitee->>API: Accept invitation
API->>Space: Activate membership
API->>Inbox: Archive invitation notification
Space-->>Invitee: Return active membership
else Invitee declines
Invitee->>API: Decline invitation
API->>Space: Remove pending invitation
API->>Inbox: Remove invitation notification
else Administrator revokes
Admin->>API: Revoke invitation
API->>Space: Remove pending invitation
API->>Inbox: Remove invitation notification
end
Only the invited user can accept or decline. A later invitation is possible after decline or revocation because those actions remove the pending relationship. Accepting keeps the notification as archived history while the user remains a member. The client can open the Space from an accepted invitation, while a pending invitation still offers accept and decline actions. If the user leaves or the Space is deleted, the related notification is hidden.
Notification creation is secondary to the invitation write. If notification creation fails, the invitation remains valid and the user can still use the invitation list.
References: server/…/space_service.go• L261-310 server/…/space_service.go• L443-568 server/…/space_service_notifications.go• L12-80 server/…/space_service_notifications.go• L82-183 proto/…/space_service.proto• L54-103 server/…/space_service_test.go• L426-501 web/…/SpaceInvitationMessage.tsx• L81-105
Membership administration
An administrator can update an accepted member's role, remove another member, and manage pending invitations. Any member can leave by deleting their own membership. The last active administrator cannot leave, be removed, or be changed to USER until another active administrator exists.
Space administration does not include direct editing or relocation of another user's memo. Memo lifecycle authority remains with the memo author. Account archival and deletion also respect the administrator invariant; a user cannot be hard-deleted while active Space memberships remain.
References: server/…/space_service.go• L657-742 store/space.go• L260-340 store/…/space.go• L334-422 server/…/user_service.go• L380-428 docs/…/multi-spaces.md• L100-136
Space-scoped memo behavior
Memo placement and audience
Placement and audience are separate memo properties. Placement says which Space feed contains a memo. Audience says who can read the memo. A memo can be assigned to one Space while still using PRIVATE, PROTECTED, or PUBLIC audience rules.
SPACE is the Space-members-only audience. It is valid only when the memo has a Space placement. The web client offers this audience as a contextual choice rather than as a global default because it has no meaning for an unassigned memo.
| Memo state | Space browsing | Ordinary read access |
|---|---|---|
| Unassigned | Not in a Space feed | Controlled by PRIVATE, PROTECTED, or PUBLIC |
Assigned with PRIVATE | Visible in the Space feed only to the author when readable | The active author |
Assigned with PROTECTED or PUBLIC | Visible in the Space feed to active members who can read it | The normal audience rule; placement alone adds no read gate |
Assigned with SPACE | Visible in the Space feed to active members | Active members of the assigned Space |
References: docs/…/multi-spaces.md• L75-98 server/…/memo_create_helpers.go• L32-56 web/…/memo.ts• L15-71
Memo participation and movement
An active member must create or assign a memo in a Space. The memo author controls later placement changes through the memo update API. A move into another Space requires active membership in the target Space.
Changing placement and audience can be one atomic update. A SPACE memo must state its new audience when it moves, and it must choose a non-Space audience when it is withdrawn. A memo with active share links cannot change to the SPACE audience until those links are revoked.
Comments remain independent memos. A comment does not inherit its context memo's Space placement or audience, so its own placement and read rules still apply.
References: server/…/memo_service.go• L306-363 server/…/memo_access.go• L94-182 server/…/memo_share_service.go• L43-57 docs/…/multi-spaces.md• L100-130
Space deletion
An administrator can hard-delete a Space. The operation removes the Space, its memberships, and every memo directly placed in it. It also removes resources owned by those memos and relations that point to them, but it never follows a relation to delete a memo in another Space or an unassigned memo.
Leaving or being removed from a Space does not move or delete the member's memos. A former member loses access to SPACE audience memos in that Space but keeps the narrow author actions that allow deletion or a permitted move.
References: proto/…/space_service.proto• L47-52 store/space.go• L227-240 store/…/space_delete.go• L12-47 docs/…/multi-spaces.md• L128-136
API and client flows
Space lifecycle API
The Space service is the control surface for Space creation, discovery, metadata, membership, invitations, and deletion. It exposes HTTP and RPC forms through the same resource model.
When an active user creates a Space, the service validates its title, optional custom ID, and optional icon. The operation creates the Space and its first ADMIN membership together. Listing returns only Spaces where the caller has active membership. A non-member, including a pending invitee, cannot use Space metadata, member, or feed requests to discover the Space.
The main lifecycle is:
flowchart LR
A[Active user] -->|CreateSpace| B[Space plus first ADMIN]
B --> C[ListSpaces for active members]
C --> D[Get or update Space metadata]
D --> E[Manage members and invitations]
E --> F[DeleteSpace by ADMIN]
F --> G[Space and directly placed memos removed]
References: proto/…/space_service.proto• L14-52 server/…/space_service.go• L86-117 server/…/space_service.go• L120-233 server/…/space_service.go• L236-258 server/…/space_icon_test.go• L17-72 web/…/CreateSpaceDialog.tsx• L28-79
Membership administration API
The service separates pending invitations from active memberships. Administrators create and list invitations under a Space, while users list their own received invitations. Member lists contain active relationships only.
The authorization boundary is applied before resource details are returned. A caller must be an active member to read Space metadata and members. An administrator is required for Space metadata changes, invitation management, role changes, member removal, and Space deletion. The invitee alone can accept or decline an invitation.
Invitation summaries are deliberately weaker than Space resources. They identify the Space and the offered role, but they do not claim that the invitee has active membership. The API also treats inactive users as unable to accept an invitation, even if an old pending offer remains for an administrator to revoke.
References: proto/…/space_service.proto• L54-131 server/…/space_service.go• L295-422 server/…/space_service.go• L443-547 server/…/space_service.go• L632-763 server/…/space_service_converters.go• L31-40 server/…/space_service_converters.go• L105-114 web/…/InviteSpaceMemberDialog.tsx• L41-106
Space selection flow
The web client loads the authenticated user's Spaces and keeps the selected Space as a browsing scope. Selecting a Space changes the collection filter to space == "spaces/{space-id}"; selecting Memos clears that filter and returns to the unassigned global collection view.
The selected Space is stored per user in session storage. If the selected Space is no longer in the user's active membership list, the client clears the selection. Routes that do not support collection scopes fall back to Home when the scope changes, while Inbox, archived content, and profiles remain user-global.
References: web/…/SpaceContext.tsx• L11-35 web/…/SpaceContext.tsx• L71-129 web/…/cel-filter.ts• L6-9 docs/…/multi-spaces.md• L171-173
Space settings flow
Settings provide the administration surface rather than a second browsing switcher. The Spaces section shows received invitations and the user's active Spaces. A selected Space opens general metadata and member views.
The client enables invitation administration only for an administrator. It resolves users before inviting them and prevents inviting the current user, an existing member, or an already invited user. Mutation success updates the relevant cached lists and invalidates memo, attachment, and statistics queries when membership changes can affect their results. Space creation can set a title, description, optional custom ID, and optional icon; the creator becomes the first administrator.
References: web/…/SpacesSection.tsx• L103-183 web/…/SpacesSection.tsx• L331-457 web/…/SpacesSection.tsx• L603-730 web/…/InviteSpaceMemberDialog.tsx• L29-107 web/…/CreateSpaceDialog.tsx• L28-79 web/…/useSpaceQueries.ts• L96-100
Client synchronization
Space, invitation, and membership mutations publish a generic Space change event. Clients invalidate their Space-related data and refetch through the normal API authorization rules. Invitation actions also update the invitee's inbox state: pending offers are actionable, accepted offers remain as archived history, and offers that no longer have a pending or accepted relationship are hidden.
The event does not contain member, invitation, or Space data. The query layer follows page tokens until it has the full list for the current user or Space. It updates local lists after successful mutations, then refreshes membership-sensitive memo and related-resource queries when a membership boundary changes.
References: server/…/space_service.go• L116-117 server/…/space_service.go• L300-310 server/…/space_service.go• L515-546 server/…/space_service_notifications.go• L37-80 server/…/space_service_notifications.go• L128-183 web/…/useSpaceQueries.ts• L102-195 web/…/useSpaceQueries.ts• L197-377 docs/…/multi-spaces.md• L175-190
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the invitation state transition aligned across the API resource, membership storage, invitation notifications, and client invitation caches. An invitation must not become active without the invitee's accept action.
- Preserve the last-active-
ADMINrule in role changes, member removal, leaving, and account deletion. - When changing memo placement or audience, keep the one-Space limit,
SPACEvalidation, target-membership check, and share-link restriction aligned. - If Space visibility or feed rules change, update point reads, collection filters, attachments, relations, notifications, search, statistics, and client invalidation together.
- Keep membership-based Space fields out of invitation-only summaries. Do not use an invitation summary as an authoritative active membership record.
- Keep user-global routes independent from the selected Space scope when changing the client context or route support rules.
- Keep icon validation and conversion aligned across create, update, storage, and client display. A nil icon means a default mark; an invalid icon must not replace a valid stored icon.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A pending invitation is treated as membership | The invitee could read Space metadata or use the Space feed before consent | Invitation and membership are separate states; only active relationships authorize Space access |
| The last active administrator leaves, is removed, or is demoted | The Space has no user who can govern it | Reject the mutation with a failed-precondition error |
A memo uses SPACE audience without a placement | The read policy has no Space to check | Reject the create or update request |
| A user assigns or moves a memo without target membership | Content could enter a Space without member participation | Require the author to be an active member of the target Space |
| A non-member requests a private Space resource | Space existence or membership data could leak | Return NotFound for member-only Space resources |
| Space deletion follows memo relations | Unrelated memos in other Spaces or global content could be deleted | Delete only memos whose direct space_id is the deleted Space |
| A client uses invitation summary fields as active membership fields | Role or member-count data can be stale or intentionally absent | Remove the invitation and refetch the authoritative Space list after acceptance |
| Invitation notification state is used as the source of invitation truth | An inbox failure or stale notification could hide a valid offer or expose an invalid one | Resolve notification payloads from the current pending invitation or active membership |
| An invalid icon passes through a client or gateway update | A Space can store unsupported display data or a valid icon can be lost | Validate the icon at the service and store boundary, and apply updates only after validation |
Key files
| File | Why to read it |
|---|---|
| docs/…/multi-spaces.md | Product boundary and access model for Spaces, memberships, memo placement, and deletion |
| proto/…/space_service.proto | Public resource names and Space, membership, invitation, and lifecycle operations |
| server/…/space_service.go | API authorization and the end-to-end Space administration flow |
| server/…/space_service_converters.go | Public Space, member, invitation, and icon representations |
| server/…/space_service_notifications.go | Invitation notification creation, visibility, and state changes |
| store/space.go | Domain states, roles, and store-level membership rules |
| store/space_icon.go | Accepted Space icon forms and validation boundary |
| store/…/space.go | Transactional persistence for Space relationships and administrator checks |
| store/…/space_delete.go | Aggregate deletion boundary for a Space and its directly placed memos |
| server/…/memo_access.go | Membership checks used by Space-scoped memo reads and writes |
| server/…/memo_service.go | Author-controlled memo placement and audience transitions |
| web/…/SpaceContext.tsx | Authenticated client scope, selection persistence, and route behavior |
| web/…/useSpaceQueries.ts | Client API queries, mutation updates, pagination, and cache invalidation |
| web/…/SpacesSection.tsx | User-facing Space list, invitations, metadata, members, and destructive actions |
| web/…/InviteSpaceMemberDialog.tsx | Existing-user lookup, role selection, and invitation submission flow |
| web/…/SpaceInvitationMessage.tsx | Pending and accepted invitation actions in the user inbox |
| web/…/SpaceMark.tsx | Shared Space identity display used by settings and selectors |
| web/…/CreateSpaceDialog.tsx | Space creation fields, custom ID validation, icon selection, and creator-admin flow |