Introducing a new way to review your PRs.

Read the announcement

usememos / memos

Memos is an open-source, self-hosted note-taking app that brings your everyday thoughts together in a personal timeline. Your data stays yours, and you choose what to keep private or share.

View on GitHub

25 documents · Updated Nov 20, 2026

docs / web-application-experience

Web application experience

The web application is the browser workspace for Memos. It starts a React client, prepares instance and user state, then presents public or signed-in memo experiences through a shared shell. Its page model connects memo collections, detail views, account work, and instance information without making each page manage its own session or navigation rules.

Application bootstrap

The client starts from web/…/main.tsx. It applies locale and theme before the first render, installs shared providers, initializes the instance profile and identity in parallel, and renders routes only after the basic readiness checks finish. This prevents route decisions and feed requests from using an unknown instance or user.

Provider composition

The provider tree gives the application shared access to server data, instance settings, identity, UI state, collection scope, memo filters, and memo composition. The router and toast surface run inside that tree, so pages can reuse the same session and query state as the shell.

This diagram shows the path from browser startup to a page.

flowchart TD
    Browser[Browser entry point] --> Setup[Apply locale and theme]
    Setup --> Providers[Install shared providers]
    Providers --> Ready[Verify instance and identity readiness]
    Ready --> Router[Render route tree]
    Router --> Experience[Render public or signed-in experience]

References: web/…/main.tsx• L22-59 web/…/main.tsx• L67-91

Service access

Shared browser service clients call the server API for instance, identity, user, memo, attachment, view, and space data. The access path carries the current token, refreshes an expired session, and retries one request when recovery succeeds. This keeps page features on one session boundary instead of giving each page separate token behavior.

References: web/…/main.tsx• L11-18 web/…/AuthCallback.tsx• L102-128

Authenticated application shell

The application shell gives route content a common workspace. Its layouts provide navigation, search, global memo entry, responsive behavior, instance branding, user theme, and scroll handling. Collection and utility pages use the same frame while public pages can omit private controls.

Session readiness

Identity readiness answers whether the client knows who is signed in. Instance profile readiness answers whether the client knows which instance it serves. These checks unlock routing and feed requests; display-sensitive settings can continue loading in the background so protected memo content does not appear with the wrong privacy or redaction rules.

When a session changes, the auth state changes with it. Sign-in loads the new identity and settings. Sign-out clears credentials, identity, and shared query data so a later visitor cannot inherit the previous user's results.

References: web/…/main.tsx• L27-58 web/…/AuthCallback.tsx• L25-26 web/…/AuthCallback.tsx• L102-128 web/…/SignUp.tsx• L81-89

The sidebar is the workspace map for memo collections and supporting services. It links to Home, Explore, calendar, map, attachments, inbox, settings, and saved views. It also lets a signed-in user switch between all memos and a selected space.

Search and new-memo actions are shell actions because they can start from many pages. Search keeps the active collection scope when the destination supports it. The new-memo action waits for the user and selected space to be ready. On small screens, route changes and editor focus wait for navigation to close so the intended target keeps focus.

References: web/…/AppSidebar.tsx• L74-160 web/…/AppSidebar.tsx• L340-451 web/…/QuickFindDialog.tsx• L21-71 web/…/SpaceSwitcher.tsx• L59-82 web/…/AppSidebarContext.tsx• L40-118

Global memo composition

The global memo composer is the cross-page entry point for writing. It opens only when the signed-in user, user settings, and selected space are ready. It captures the active user and space when it opens, closes competing sidebar surfaces, and returns focus after the dialog closes.

The composer is also a session boundary. A user or readiness change closes it, and the open dialog cannot switch to another session. A save cannot be interrupted by a close action. Home keeps a separate inline editor for the current collection while the global composer remains available from the shell.

References: web/…/GlobalMemoEditorContext.tsx• L40-58 web/…/GlobalMemoEditorContext.tsx• L80-130 web/…/GlobalMemoEditorContext.tsx• L133-171 web/…/Home.tsx• L47-89

Route model

Routing separates public discovery, signed-in work, and authentication. The route tree nests shared layouts and access guards. Collection URLs carry creator, space, filter, and date scope so a page can restore the collection that the user intended to view.

Route groups

The route tree presents these main product areas:

Route groupProduct experienceAccess shape
/ and /archivedPersonal and archived memo collectionsHome can show public creator scopes; private work requires a user
/explore and creator-filtered Home URLsPublic discovery and creator-scoped collectionsReadable where visibility permits; writing requires the current creator
/calendar/...Date-based memo collectionReadable public memos; writing requires the current creator
/mapLocation-based memo explorationAuthenticated and initialized
/memos/:uid and shared memo linksMemo detail and collaborationDirect details follow memo access; share links use their token
/attachments, /inbox, /setting, /viewsSigned-in workspace servicesAuthenticated and initialized
/auth/*Sign-in, sign-up, administrator sign-in, and OAuth returnGuest routes except the callback's session work
/spaces/:spaceUid/*Space-scoped collections and resourcesAuthenticated and initialized

The old creator profile route redirects to Home with its creator query preserved. This keeps personal, Explore, and creator views in one collection model.

References: web/…/routes.ts• L4-35 web/…/routes.ts• L44-67 web/…/index.tsx• L58-162

Access boundaries

Route guards apply the least access needed for each experience. Instance initialization gates pages that need public instance settings. Authentication gates private work. Full initialization gates pages that need all display-sensitive settings.

Anonymous visitors go to Explore unless a creator filter keeps the requested collection meaningful. Sign-in stores a safe return path. OAuth callbacks stay outside guest-only routing so a pending provider login can finish even when another tab already has a session. A space route waits for its selected space before showing collection data or the composer, and separates loading, unavailable, and retryable errors.

References: web/…/guards.tsx• L8-56 web/…/index.tsx• L65-155 web/…/SpaceRoute.tsx• L10-39 web/…/AuthCallback.tsx• L32-84

Shared client state

Shared state keeps related pages aligned. React Query holds server data and freshness. Focused React contexts hold identity, instance state, space scope, URL-backed memo filters, reading preferences, shell state, mention resolution, and the global composer.

Identity and instance state

The identity state represents the current user and user settings. It restores or refreshes a session, verifies the user, and loads settings that affect memo display. The instance state represents the instance profile and general settings. It provides the information used for setup routing, branding, access policy, and managed resource links.

References: web/…/main.tsx• L27-58 web/…/SignIn.tsx• L19-29 web/…/About.tsx• L47-61

Space selection

A space is a named memo collection that becomes the current working scope. The space state derives the selection from the URL and exposes either that space or the all-memos scope to collection pages. The same scope controls collection reads and memo creation, which prevents a page from displaying one collection while saving into another.

References: web/…/Home.tsx• L25-45 web/…/Attachments.tsx• L68-99 web/…/SpaceRoute.tsx• L11-16 web/…/SpaceSwitcher.tsx• L59-82

Memo navigation state

Memo filters are shared URL state. Collection pages and shell controls can combine creator and space scope with saved views, search terms, tags, properties, and time ranges. Reading preferences keep timeline choices consistent across Home and Explore, while other collection views use their normal presentation.

Saved views are named filters that users can validate, save, edit, delete, reorder, and apply from the sidebar. The Views page also provides examples and a field guide so a user can start with a supported filter shape. It opens the create or edit form from route state, checks a filter before saving, updates the list immediately when the order changes, and clears the active view when that view is deleted.

References: web/…/MemoViews.tsx• L47-221 web/…/MemoViews.tsx• L270-310 web/…/MemoViews.tsx• L312-520 web/…/MemoViews.tsx• L621-731 web/…/Home.tsx• L23-45

Live data freshness

The client treats server data as shared query data rather than page-local copies. Live memo, comment, and reaction events mark affected lists and details as stale so active pages refresh. Token refresh on focus and request recovery reduce errors caused by an expired session.

References: web/…/main.tsx• L43-49 web/…/AuthCallback.tsx• L102-128

Page-level product experiences

The page layer turns the shared shell and state into product work areas. Collection pages use a common memo feed model with different creator, space, time, and location scopes. Detail and utility pages add focused ways to read, manage, and respond to memo data.

Memo collections

Home is the main memo feed and the primary writing entry point. It shows normal memos, filters, saved views, and pinned items when the feed represents one creator. The inline editor appears only in the current user's creator scope, follows the selected space, and can use the active time filter as its default creation time.

Archived shows the user's archived memos through the same filter and sort model. The empty Home state and About page can reopen the welcome guide for the current account. The guide introduces writing, keeping, and sharing through the product's main areas.

For memo writing, reading, search, filtering, and collaboration, see Memo authoring and browsing UI.

References: web/…/Home.tsx• L19-89 web/…/Archived.tsx• L11-41 web/…/About.tsx• L47-71 web/…/About.tsx• L142-162

Calendar collections

Calendar is a date-based collection view. It normalizes incomplete or invalid dates, loads readable memos for the selected period, and lets a user select a day to read its memos. A signed-in user can create a memo for that day when the active creator scope belongs to that user.

For date navigation and temporal memo views, see Calendar and temporal memo views.

References: web/…/Calendar.tsx• L7-20 web/…/CalendarView.tsx• L44-185

Map exploration

Map exploration collects memos with location data. It works in the global workspace and in a selected space, so the URL keeps location browsing aligned with other collection pages. A selected pin or cluster opens a memo reading panel. The current user can create a memo from a permitted location.

For the location-focused experience, see Map-based memo exploration.

References: web/…/MapView.tsx• L26-155 web/…/MapCanvas.tsx• L128-239

Memo details

Memo detail supports direct memo links and token-based shared links. It loads the memo and its parent when available, presents comments for normal access, and gives the shell the actions needed for editing, commenting, and sharing. Shared links remain read-only and use attachment links scoped to the share token.

The page preserves the user's return context. A direct public visit can return to Explore. A private parent can be unavailable to a guest without making the child memo unusable. Content hidden by tag settings stays hidden in both the memo body and shell details until the user reveals it. A shared link has no comment or edit actions.

References: web/…/MemoDetail.tsx• L92-137 web/…/MemoDetail.tsx• L143-231 web/…/MemoDetail.tsx• L237-304

Workspace services

The Inbox presents comment, mention, and space invitation notices. It supports all, unread, and archived views. Attachments presents media, documents, audio, and unused uploads with preview and cleanup actions. Unused uploads are limited to the all-memos scope and the current creator, and cleanup runs in bounded batches.

References: web/…/Inboxes.tsx• L13-70 web/…/Attachments.tsx• L68-120 web/…/Attachments.tsx• L127-147 web/…/Attachments.tsx• L150-281

Settings and account management

Settings selects user or administrator work from the URL hash. User areas cover account data, spaces, tokens, preferences, webhooks, tags, and memo transfer. Administrator areas cover instance behavior, members, storage, notifications, SSO, AI, and resource rules. The page exposes administrator areas only to users with the administrator role.

For the complete account, instance, attachment, inbox, and administration flows, see Web settings and account management.

References: web/…/Setting.tsx• L13-67 web/…/settingSections.ts• L37-176

Authentication experiences

Sign-in and sign-up follow instance policy. Sign-in can use a password or configured identity providers. Sign-up supports first-run administrator setup, open registration, closed registration, and provider-only registration.

Password registration can require a challenge. The challenge proof accompanies account creation and the immediate sign-in. OAuth callbacks validate state and PKCE data before code exchange. They support both sign-in and linking an identity to the current account, then return the user to a safe path.

Administrator sign-in is a focused password route for the first-run or administrator entry path. It shares the password sign-in form but provides a clear return link to normal sign-in.

References: web/…/SignIn.tsx• L19-79 web/…/SignUp.tsx• L25-195 web/…/AdminSignIn.tsx• L8-29 web/…/AuthCallback.tsx• L22-164

Instance information

About is the public instance information view. It shows the instance identity, description, build identity, demo status, branding note, and links to project resources. A recognized release links to its release page. A development build with a valid commit identifier links to that commit. Non-demo instances can reopen the welcome guide from this page.

References: web/…/About.tsx• L47-85 web/…/About.tsx• L87-162

Recovery pages

Not Found and Permission Denied provide clear terminal states for missing resources and forbidden access. They keep recovery and access errors distinct from normal page content.

References: web/…/NotFound.tsx• L3-13 web/…/PermissionDenied.tsx• L3-13

Change checklist

When these files or sections are changed, remember to consider these:

  • Route paths, access guards, sidebar route kinds, and redirect targets must stay aligned.
  • Creator, space, filter, date, and map state must move together between collection pages.
  • Identity and instance readiness must preserve the difference between route readiness and display-setting readiness.
  • Global composition must capture the active user and space, return focus safely, and close on session changes without interrupting a save.
  • Authentication state, challenge proof, OAuth state, PKCE data, and safe return paths must remain one flow.
  • Attachment cleanup must remain limited to unused uploads in the permitted all-memos scope.
  • Saved-view validation, route-state entry, filter fields, ordering, and the filter fields used by collection pages must stay compatible.
  • Detail-page reveal state must stay aligned with the memo information exposed by the shell.
  • About build links must keep release tags and valid development commit identifiers distinct, and the welcome guide must remain unavailable for demo instances.

Important failure modes

TriggerConsequenceGuard
Instance profile fails to loadThe client can treat a temporary error as a new instanceSetup routing requires successful profile readiness
Anonymous user opens a private routePrivate work could render without a sessionRoute guards redirect to sign-in
Session changes while the global composer is openA draft could use the wrong identity or spaceThe composer closes on identity and readiness changes
OAuth state or PKCE data is invalidSign-in or account linking can fail or redirect unsafelyThe callback validates state and re-validates the return path
Challenge proof is staleRegistration fails even when the credentials are validChallenge failure resets the challenge widget
Selected space cannot loadThe page could show or create data in the wrong collectionSpace routing separates loading from unavailable access and offers retry only for recoverable errors
Unused attachment cleanup runs outside all-memos scopeFiles from another scope could be deletedThe unused view and cleanup require the permitted scope
A hidden memo exposes shell detailsHeadings or parent text can bypass content protectionDetail reveal state also controls shell detail content
A saved view is deleted while it is activeCollection pages can keep a filter that no longer existsView deletion clears the active view before shared filters continue
A saved view order changes without a stored responseThe sidebar can show an order that differs from the saved orderReordering updates the visible list at once and restores stored data after a failed save
A development build has an invalid commit identifierThe About page can link to a non-existent source revisionAbout links only commit-shaped identifiers and otherwise shows the build version without a link

Key files

FileWhy to read it
web/…/main.tsxBrowser entry point, provider order, readiness, and live refresh
web/…/App.tsxApplication-wide theme, branding, and route outlet behavior
web/…/index.tsxRoute tree, layouts, and access boundaries
web/…/routes.tsStable paths and collection URL rules
web/…/guards.tsxInstance, guest, authenticated, and full-readiness gates
web/…/SpaceRoute.tsxSpace readiness and unavailable-space recovery boundary
web/…/RootLayout.tsxShared shell and route content boundary
web/…/AppSidebar.tsxPrimary navigation and shell actions
web/…/AuthContext.tsxIdentity and user-setting readiness
web/…/InstanceContext.tsxInstance profile, policy, and settings readiness
web/…/SpaceContext.tsxCurrent collection scope
web/…/MemoFilterContext.tsxShared URL-backed memo filters and saved-view selection
web/…/GlobalMemoEditorContext.tsxCross-page composition, focus return, and session-safe close behavior
web/…/Home.tsxMain memo collection and inline authoring experience
web/…/MemoDetail.tsxDirect and shared memo reading experience
web/…/MemoViews.tsxSaved-view examples, validation, creation, editing, ordering, and deletion
web/…/SignIn.tsxInstance-driven sign-in options
web/…/SignUp.tsxFirst-run, registration, provider, and challenge flows
web/…/AuthCallback.tsxOAuth sign-in and identity-link return flow
web/…/About.tsxPublic instance identity, build links, project links, and guide access