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
Navigation shell
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 group | Product experience | Access shape |
|---|---|---|
/ and /archived | Personal and archived memo collections | Home can show public creator scopes; private work requires a user |
/explore and creator-filtered Home URLs | Public discovery and creator-scoped collections | Readable where visibility permits; writing requires the current creator |
/calendar/... | Date-based memo collection | Readable public memos; writing requires the current creator |
/map | Location-based memo exploration | Authenticated and initialized |
/memos/:uid and shared memo links | Memo detail and collaboration | Direct details follow memo access; share links use their token |
/attachments, /inbox, /setting, /views | Signed-in workspace services | Authenticated and initialized |
/auth/* | Sign-in, sign-up, administrator sign-in, and OAuth return | Guest routes except the callback's session work |
/spaces/:spaceUid/* | Space-scoped collections and resources | Authenticated 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
| Trigger | Consequence | Guard |
|---|---|---|
| Instance profile fails to load | The client can treat a temporary error as a new instance | Setup routing requires successful profile readiness |
| Anonymous user opens a private route | Private work could render without a session | Route guards redirect to sign-in |
| Session changes while the global composer is open | A draft could use the wrong identity or space | The composer closes on identity and readiness changes |
| OAuth state or PKCE data is invalid | Sign-in or account linking can fail or redirect unsafely | The callback validates state and re-validates the return path |
| Challenge proof is stale | Registration fails even when the credentials are valid | Challenge failure resets the challenge widget |
| Selected space cannot load | The page could show or create data in the wrong collection | Space routing separates loading from unavailable access and offers retry only for recoverable errors |
| Unused attachment cleanup runs outside all-memos scope | Files from another scope could be deleted | The unused view and cleanup require the permitted scope |
| A hidden memo exposes shell details | Headings or parent text can bypass content protection | Detail reveal state also controls shell detail content |
| A saved view is deleted while it is active | Collection pages can keep a filter that no longer exists | View deletion clears the active view before shared filters continue |
| A saved view order changes without a stored response | The sidebar can show an order that differs from the saved order | Reordering updates the visible list at once and restores stored data after a failed save |
| A development build has an invalid commit identifier | The About page can link to a non-existent source revision | About links only commit-shaped identifiers and otherwise shows the build version without a link |
Key files
| File | Why to read it |
|---|---|
| web/…/main.tsx | Browser entry point, provider order, readiness, and live refresh |
| web/…/App.tsx | Application-wide theme, branding, and route outlet behavior |
| web/…/index.tsx | Route tree, layouts, and access boundaries |
| web/…/routes.ts | Stable paths and collection URL rules |
| web/…/guards.tsx | Instance, guest, authenticated, and full-readiness gates |
| web/…/SpaceRoute.tsx | Space readiness and unavailable-space recovery boundary |
| web/…/RootLayout.tsx | Shared shell and route content boundary |
| web/…/AppSidebar.tsx | Primary navigation and shell actions |
| web/…/AuthContext.tsx | Identity and user-setting readiness |
| web/…/InstanceContext.tsx | Instance profile, policy, and settings readiness |
| web/…/SpaceContext.tsx | Current collection scope |
| web/…/MemoFilterContext.tsx | Shared URL-backed memo filters and saved-view selection |
| web/…/GlobalMemoEditorContext.tsx | Cross-page composition, focus return, and session-safe close behavior |
| web/…/Home.tsx | Main memo collection and inline authoring experience |
| web/…/MemoDetail.tsx | Direct and shared memo reading experience |
| web/…/MemoViews.tsx | Saved-view examples, validation, creation, editing, ordering, and deletion |
| web/…/SignIn.tsx | Instance-driven sign-in options |
| web/…/SignUp.tsx | First-run, registration, provider, and challenge flows |
| web/…/AuthCallback.tsx | OAuth sign-in and identity-link return flow |
| web/…/About.tsx | Public instance identity, build links, project links, and guide access |