How anyproto/anytype-ts works
1. Repository purpose and system boundary
This repo is the Anytype Desktop client: a cross-platform, local-first knowledge app built around an Electron shell and a large TypeScript renderer. The desktop UI is only one layer; the actual data engine lives outside this repo in the anytype-heart middleware, which is fetched/built separately and talks to this client over a generated gRPC/protobuf API.
2. Primary runtime model
The app runs in three major contexts: Electron main process, Electron renderer process, and supporting worker processes. There is also a web-only mode (start:web) that uses the same renderer code without the Electron shell, plus a browser extension build under extension/ and dist/extension/.
3. Electron host layer
electron/ts/* owns application lifecycle, window creation, menus, update logic, safe storage, and the embedded local server. electron/js/preload.cjs bridges privileged Electron APIs into the renderer. This layer is the boundary for OS integration, signing/notarization, and platform-specific behavior.
4. Renderer application architecture
src/ts/app.tsx, entry.tsx, and entry.web.tsx boot the UI. The renderer is organized as a component-heavy React/TypeScript app with clear feature shells: page/, popup/, sidebar/, header/, footer/, widget/, preview/, notification/, and domain-specific block editors under component/block/*. The structure suggests the product is centered around composable “blocks,” objects, pages, and views rather than a single document/page model.
5. State and domain model flow
src/ts/store/* contains the main client state surfaces for auth, blocks, chat, comments, membership, menus, popups, progress, records, notifications, and extension state. src/ts/model/* and src/ts/interface/* define the domain vocabulary used by components and stores, while src/ts/lib/* provides shared behavior such as routing, keyboard handling, previews, relations, history, and rendering helpers. UI components read from stores and drive actions back through the lib/api layer.
6. Backend communication boundary
src/ts/lib/api/* is the client-side transport layer. It maps app actions and responses into the middleware protocol, using generated protobuf bindings and service registries from dist/lib/ and build scripts under scripts/. This is the main seam between the UI/client and the local sync/storage engine, and it is where most data persistence, sync, and object mutations cross process boundaries.
7. Local-first and sync-centric features
The architecture emphasizes offline operation and deferred synchronization. The UI includes explicit surfaces for sync status, queued/synced/error states, offline mode, and local-only behavior. Data flows are therefore not “request/response to a remote server” but “local mutation → middleware sync engine → remote/peer replication when available.”
8. Specialized feature subsystems
Several large verticals are first-class and architecturally distinct:
- Auth/onboarding: login, setup, PIN, migration, onboarding, and space selection.
- Content editing: block-based page editing, tables, embeds, media, relations, and layouts.
- Dataviews: board, calendar, gallery, graph, grid/list, filters, sorting, grouping, and templates.
- Chat/comments: dedicated chat and discussion flows with attachments, reactions, and reply threads.
- Settings/membership/import-export: account, API, language, spaces, storage, import from CSV/Notion/Obsidian, and export to markdown/protobuf.
9. Worker and rendering offload
src/ts/workers/* and dist/workers/* handle heavier visual or compute tasks such as graph rendering and onboarding graph animations, plus PDF work. The app also keeps several third-party libraries stubbed in src/stubs/, which is a clue that some features are lazily loaded or isolated for bundling/performance reasons.
10. Browser extension and native messaging bridge
The extension code in extension/ and packaged assets in dist/extension/ implement popup/auth/iframe flows for clipping or integrating browser content. go/nativeMessagingHost.go and the Electron install hook for the native messaging host indicate a desktop-to-browser bridge: the extension communicates with the local desktop app via native messaging, not directly with the sync backend.
11. Build, packaging, and release pipeline
Vite config files (vite*.config.ts) split builds for desktop, web, extension, and workers. scripts/ contains repo-specific generation and packaging tasks such as icon generation, release notes, proto generation, and service registry creation. dist/ is a committed output tree used for packaged assets, generated bindings, and release artifacts.
12. Tooling and quality gates
Storybook is used extensively for isolated component development and visual verification. Vitest covers the shared domain logic in src/ts/lib and src/ts/model. CI is split across GitHub workflows for build, cleanup, mirroring, nightly builds, and release automation, with linting/typechecking enforced through the usual JS tooling and repo-specific policies.
Main entry points: index.ts UI shells · main.ts Main process · dispatcher.ts API transport · vite.config.ts Vite builds
Components 26
Electron host
Main-process shell and OS integration boundary
- Main process · Bootstraps the desktop app and coordinates host services
electron/ts/main.ts - Window mgmt · Creates and manages app windows and platform behavior
electron/ts/window.ts - Menus · Native menu definitions and app actions
electron/ts/menu.ts - Local server · Embedded localhost server used by the desktop client
electron/ts/server.ts - Secure storage · Safe storage and secret handling boundary
electron/ts/safeStorage.ts - Preload bridge · Exposes privileged Electron APIs to the renderer
electron/js/preload.cjs
Renderer app
React/TypeScript client UI and local state
- App entry · Boots desktop and web renderer entrypoints
src/ts/app.tsx - UI shells · Top-level page, popup, sidebar, header, footer, preview, notification, and widget surfaces
src/ts/component/index.ts - Block editors · Composable block editor components for pages, tables, embeds, media, relations, and chat
src/ts/component/block/index.tsx - Dataviews · Board, calendar, gallery, graph, grid, list, timeline, filters, and templates
src/ts/component/block/dataview.tsx - Auth flow · Login, setup, PIN, migration, onboarding, and space selection
src/ts/component/page/auth/login.tsx - Settings · Account, API, language, membership, import/export, PIN, spaces, and storage
src/ts/component/page/main/settings/index.tsx - Chat & comments · Chat threads, replies, reactions, attachments, and discussion components
src/ts/component/block/chat.tsx - Stores · Auth, blocks, chat, comments, membership, menus, popups, progress, records, notifications, and extension state
src/ts/store/index.ts - Domain model · Shared vocabulary for blocks, views, relations, spaces, notifications, and membership
src/ts/model/index.ts - Client lib · Routing, keyboard handling, history, preview, relations, renderer helpers, and utilities
src/ts/lib/index.ts - API transport · Client-side command/response mapping to the middleware protocol
src/ts/lib/api/dispatcher.ts
Browser extension
Popup, auth, iframe, and content bridge assets
- Extension app · Extension bootstrap for auth, popup, and iframe flows
extension/entry.tsx - Extension UI · Popup, auth, iframe, and success views for browser integration
extension/popup.tsx - Native host · Native messaging host used to connect the browser extension to the desktop app
go/nativeMessagingHost.go
Workers
Offloaded rendering and compute tasks
- Graph worker · Offloads graph rendering and onboarding animation work
src/ts/workers/pixi-worker-entry.ts - PDF worker · Dedicated PDF processing worker in the committed worker bundle
dist/workers/pdf.worker.mjs
Build & release
Generated assets, packaging, and release tooling
- Generated dist · Committed generated bindings, locale data, and packaged runtime assets
dist/lib/json/generated/.gitignore - Build scripts · Proto generation, service registry generation, build orchestration, release notes, and packaging helpers
scripts/build-electron.js - Vite builds · Separate desktop, web, extension, and worker build pipelines
vite.config.ts
Other components
- Middleware engine · External anytype-heart local-first data engine and sync/storage boundary
Connections 27
- Main process → Window mgmt: creates · Main process opens and manages windows
- Main process → Menus: installs · Main process wires native menus and commands
- Main process → Local server: hosts · Main process starts the local server
- Main process → Secure storage: uses · Main process handles secrets and safe storage
- Main process → Preload bridge: bridges · Preload is the privileged boundary into renderer code
- App entry → UI shells: renders · Bootstrapped UI mounts the main shells
- UI shells → Block editors: contains · Shells host the block-based editor surfaces
- UI shells → Dataviews: contains · Shells present dataview modes and filters
- UI shells → Auth flow: routes to · Shells switch into onboarding and login flows
- UI shells → Settings: routes to · Shells expose account and app settings
- UI shells → Chat & comments: contains · Shells surface discussion and chat features
- UI shells → Stores: reads/writes · UI is driven by client stores
- Block editors → Client lib: uses · Editors share routing, selection, preview, and input helpers
- Dataviews → Domain model: shapes · Views and filters are defined by shared domain types
- Stores → API transport: dispatches · Store actions are translated into protocol commands
- Client lib → API transport: calls · Shared logic reaches the transport seam for data operations
- API transport → Generated dist: loads · Transport depends on generated protobuf and registry artifacts
- API transport → Middleware engine: talks to · Client requests cross the process boundary to the local engine
- Extension app → Extension UI: boots · Extension entrypoint mounts popup, auth, and iframe flows
- Extension UI → Native host: connects via · Extension integrates with the desktop app through native messaging
- Graph worker → Dataviews: supports · Worker offloads graph-related rendering and animation
- PDF worker → Block editors: supports · Worker handles heavyweight document/media rendering
- Build scripts → Generated dist: generates · Scripts produce bindings, registries, and release artifacts
- Vite builds → App entry: builds · Vite builds the renderer entrypoints
- Vite builds → Extension app: builds · Vite builds the browser extension
- Vite builds → Graph worker: builds · Vite bundles worker entrypoints
- Main process → API transport: coordinates · Host layer and client transport meet at the app boundary