# anyproto/anytype-ts architecture

> Architecture diagram of the GitHub repository anyproto/anytype-ts, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anyproto/anytype-ts
- Repository: https://github.com/anyproto/anytype-ts

## Overview

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: [`src/ts/component/index.ts`](https://github.com/anyproto/anytype-ts/blob/develop/src/ts/component/index.ts) (UI shells), [`electron/ts/main.ts`](https://github.com/anyproto/anytype-ts/blob/develop/electron/ts/main.ts) (Main process), [`src/ts/lib/api/dispatcher.ts`](https://github.com/anyproto/anytype-ts/blob/develop/src/ts/lib/api/dispatcher.ts) (API transport), [`vite.config.ts`](https://github.com/anyproto/anytype-ts/blob/develop/vite.config.ts) (Vite builds)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_electron["Electron host"]
  node_n_electron_main["Main process<br/>electron lifecycle<br/>[main.ts]"]
  node_n_electron_window["Window mgmt<br/>electron windows<br/>[window.ts]"]
  node_n_electron_menu["Menus<br/>[menu.ts]"]
  node_n_electron_server["Local server<br/>electron server<br/>[server.ts]"]
  node_n_electron_secure["Secure storage<br/>[safeStorage.ts]"]
  node_n_electron_preload["Preload bridge<br/>electron bridge<br/>[preload.cjs]"]
end

subgraph group_g_renderer["Renderer app"]
  node_n_renderer_boot["App entry<br/>renderer bootstrap<br/>[app.tsx]"]
  node_n_renderer_shells["UI shells<br/>react shells<br/>[index.ts]"]
  node_n_renderer_blocks["Block editors<br/>content editing<br/>[index.tsx]"]
  node_n_renderer_dataviews["Dataviews<br/>views and filters<br/>[dataview.tsx]"]
  node_n_renderer_auth["Auth flow<br/>onboarding and login<br/>[login.tsx]"]
  node_n_renderer_settings["Settings<br/>account and storage<br/>[index.tsx]"]
  node_n_renderer_chat["Chat & comments<br/>discussion surfaces<br/>[chat.tsx]"]
  node_n_state_store["Stores<br/>client state<br/>[index.ts]"]
  node_n_domain_model["Domain model<br/>types and models<br/>[index.ts]"]
  node_n_client_lib["Client lib<br/>shared logic<br/>[index.ts]"]
  node_n_api_transport["API transport<br/>grpc client<br/>[dispatcher.ts]"]
end

subgraph group_g_extension["Browser extension"]
  node_n_extension_app["Extension app<br/>browser extension<br/>[entry.tsx]"]
  node_n_extension_runtime["Extension UI<br/>extension surfaces<br/>[popup.tsx]"]
  node_n_native_host["Native host<br/>go bridge"]
end

subgraph group_g_workers["Workers"]
  node_n_worker_graph["Graph worker<br/>render worker"]
  node_n_worker_pdf["PDF worker<br/>[pdf.worker.mjs]"]
end

subgraph group_g_build["Build & release"]
  node_n_dist_gen["Generated dist<br/>built assets<br/>[.gitignore]"]
  node_n_scripts["Build scripts<br/>generation and packaging<br/>[build-electron.js]"]
  node_n_vite["Vite builds<br/>bundler configs<br/>[vite.config.ts]"]
end

node_n_middleware[("Middleware engine<br/>external sync backend")]

node_n_electron_main -->|"creates"| node_n_electron_window
node_n_electron_main -->|"installs"| node_n_electron_menu
node_n_electron_main -->|"hosts"| node_n_electron_server
node_n_electron_main -->|"uses"| node_n_electron_secure
node_n_electron_main -->|"bridges"| node_n_electron_preload
node_n_renderer_boot -->|"renders"| node_n_renderer_shells
node_n_renderer_shells -->|"contains"| node_n_renderer_blocks
node_n_renderer_shells -->|"contains"| node_n_renderer_dataviews
node_n_renderer_shells -->|"routes to"| node_n_renderer_auth
node_n_renderer_shells -->|"routes to"| node_n_renderer_settings
node_n_renderer_shells -->|"contains"| node_n_renderer_chat
node_n_renderer_shells -->|"reads/writes"| node_n_state_store
node_n_renderer_blocks -->|"uses"| node_n_client_lib
node_n_renderer_dataviews -->|"shapes"| node_n_domain_model
node_n_state_store -->|"dispatches"| node_n_api_transport
node_n_client_lib -->|"calls"| node_n_api_transport
node_n_api_transport -->|"loads"| node_n_dist_gen
node_n_api_transport -->|"talks to"| node_n_middleware
node_n_extension_app -->|"boots"| node_n_extension_runtime
node_n_extension_runtime -->|"connects via"| node_n_native_host
node_n_worker_graph -->|"supports"| node_n_renderer_dataviews
node_n_worker_pdf -->|"supports"| node_n_renderer_blocks
node_n_scripts -->|"generates"| node_n_dist_gen
node_n_vite -->|"builds"| node_n_renderer_boot
node_n_vite -->|"builds"| node_n_extension_app
node_n_vite -->|"builds"| node_n_worker_graph
node_n_electron_main -.->|"coordinates"| node_n_api_transport

click node_n_electron_main "https://github.com/anyproto/anytype-ts/blob/develop/electron/ts/main.ts"
click node_n_electron_window "https://github.com/anyproto/anytype-ts/blob/develop/electron/ts/window.ts"
click node_n_electron_menu "https://github.com/anyproto/anytype-ts/blob/develop/electron/ts/menu.ts"
click node_n_electron_server "https://github.com/anyproto/anytype-ts/blob/develop/electron/ts/server.ts"
click node_n_electron_secure "https://github.com/anyproto/anytype-ts/blob/develop/electron/ts/safeStorage.ts"
click node_n_electron_preload "https://github.com/anyproto/anytype-ts/blob/develop/electron/js/preload.cjs"
click node_n_renderer_boot "https://github.com/anyproto/anytype-ts/blob/develop/src/ts/app.tsx"
click node_n_renderer_shells "https://github.com/anyproto/anytype-ts/blob/develop/src/ts/component/index.ts"
click node_n_renderer_blocks "https://github.com/anyproto/anytype-ts/blob/develop/src/ts/component/block/index.tsx"
click node_n_renderer_dataviews "https://github.com/anyproto/anytype-ts/blob/develop/src/ts/component/block/dataview.tsx"
click node_n_renderer_auth "https://github.com/anyproto/anytype-ts/blob/develop/src/ts/component/page/auth/login.tsx"
click node_n_renderer_settings "https://github.com/anyproto/anytype-ts/blob/develop/src/ts/component/page/main/settings/index.tsx"
click node_n_renderer_chat "https://github.com/anyproto/anytype-ts/blob/develop/src/ts/component/block/chat.tsx"
click node_n_state_store "https://github.com/anyproto/anytype-ts/blob/develop/src/ts/store/index.ts"
click node_n_domain_model "https://github.com/anyproto/anytype-ts/blob/develop/src/ts/model/index.ts"
click node_n_client_lib "https://github.com/anyproto/anytype-ts/blob/develop/src/ts/lib/index.ts"
click node_n_api_transport "https://github.com/anyproto/anytype-ts/blob/develop/src/ts/lib/api/dispatcher.ts"
click node_n_extension_app "https://github.com/anyproto/anytype-ts/blob/develop/extension/entry.tsx"
click node_n_extension_runtime "https://github.com/anyproto/anytype-ts/blob/develop/extension/popup.tsx"
click node_n_native_host "https://github.com/anyproto/anytype-ts/blob/develop/go/nativeMessagingHost.go"
click node_n_worker_graph "https://github.com/anyproto/anytype-ts/blob/develop/src/ts/workers/pixi-worker-entry.ts"
click node_n_worker_pdf "https://github.com/anyproto/anytype-ts/blob/develop/dist/workers/pdf.worker.mjs"
click node_n_dist_gen "https://github.com/anyproto/anytype-ts/blob/develop/dist/lib/json/generated/.gitignore"
click node_n_scripts "https://github.com/anyproto/anytype-ts/blob/develop/scripts/build-electron.js"
click node_n_vite "https://github.com/anyproto/anytype-ts/blob/develop/vite.config.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_electron_main,node_n_electron_window,node_n_electron_menu,node_n_electron_server,node_n_electron_secure,node_n_electron_preload toneBlue
class node_n_renderer_boot,node_n_renderer_shells,node_n_renderer_blocks,node_n_renderer_dataviews,node_n_renderer_auth,node_n_renderer_settings,node_n_renderer_chat,node_n_state_store,node_n_domain_model,node_n_client_lib,node_n_api_transport toneAmber
class node_n_extension_app,node_n_extension_runtime,node_n_native_host toneMint
class node_n_worker_graph,node_n_worker_pdf toneRose
class node_n_dist_gen,node_n_scripts,node_n_vite toneIndigo
class node_n_middleware toneNeutral
```

## Components

### Electron host

Main-process shell and OS integration boundary

- [Main process](https://github.com/anyproto/anytype-ts/blob/develop/electron/ts/main.ts): electron lifecycle · Bootstraps the desktop app and coordinates host services · `electron/ts/main.ts`
- [Window mgmt](https://github.com/anyproto/anytype-ts/blob/develop/electron/ts/window.ts): electron windows · Creates and manages app windows and platform behavior · `electron/ts/window.ts`
- [Menus](https://github.com/anyproto/anytype-ts/blob/develop/electron/ts/menu.ts): electron menus · Native menu definitions and app actions · `electron/ts/menu.ts`
- [Local server](https://github.com/anyproto/anytype-ts/blob/develop/electron/ts/server.ts): electron server · Embedded localhost server used by the desktop client · `electron/ts/server.ts`
- [Secure storage](https://github.com/anyproto/anytype-ts/blob/develop/electron/ts/safeStorage.ts): electron secure storage · Safe storage and secret handling boundary · `electron/ts/safeStorage.ts`
- [Preload bridge](https://github.com/anyproto/anytype-ts/blob/develop/electron/js/preload.cjs): electron bridge · Exposes privileged Electron APIs to the renderer · `electron/js/preload.cjs`

### Renderer app

React/TypeScript client UI and local state

- [App entry](https://github.com/anyproto/anytype-ts/blob/develop/src/ts/app.tsx): renderer bootstrap · Boots desktop and web renderer entrypoints · `src/ts/app.tsx`
- [UI shells](https://github.com/anyproto/anytype-ts/blob/develop/src/ts/component/index.ts): react shells · Top-level page, popup, sidebar, header, footer, preview, notification, and widget surfaces · `src/ts/component/index.ts`
- [Block editors](https://github.com/anyproto/anytype-ts/blob/develop/src/ts/component/block/index.tsx): content editing · Composable block editor components for pages, tables, embeds, media, relations, and chat · `src/ts/component/block/index.tsx`
- [Dataviews](https://github.com/anyproto/anytype-ts/blob/develop/src/ts/component/block/dataview.tsx): views and filters · Board, calendar, gallery, graph, grid, list, timeline, filters, and templates · `src/ts/component/block/dataview.tsx`
- [Auth flow](https://github.com/anyproto/anytype-ts/blob/develop/src/ts/component/page/auth/login.tsx): onboarding and login · Login, setup, PIN, migration, onboarding, and space selection · `src/ts/component/page/auth/login.tsx`
- [Settings](https://github.com/anyproto/anytype-ts/blob/develop/src/ts/component/page/main/settings/index.tsx): account and storage · Account, API, language, membership, import/export, PIN, spaces, and storage · `src/ts/component/page/main/settings/index.tsx`
- [Chat & comments](https://github.com/anyproto/anytype-ts/blob/develop/src/ts/component/block/chat.tsx): discussion surfaces · Chat threads, replies, reactions, attachments, and discussion components · `src/ts/component/block/chat.tsx`
- [Stores](https://github.com/anyproto/anytype-ts/blob/develop/src/ts/store/index.ts): client state · Auth, blocks, chat, comments, membership, menus, popups, progress, records, notifications, and extension state · `src/ts/store/index.ts`
- [Domain model](https://github.com/anyproto/anytype-ts/blob/develop/src/ts/model/index.ts): types and models · Shared vocabulary for blocks, views, relations, spaces, notifications, and membership · `src/ts/model/index.ts`
- [Client lib](https://github.com/anyproto/anytype-ts/blob/develop/src/ts/lib/index.ts): shared logic · Routing, keyboard handling, history, preview, relations, renderer helpers, and utilities · `src/ts/lib/index.ts`
- [API transport](https://github.com/anyproto/anytype-ts/blob/develop/src/ts/lib/api/dispatcher.ts): grpc client · 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](https://github.com/anyproto/anytype-ts/blob/develop/extension/entry.tsx): browser extension · Extension bootstrap for auth, popup, and iframe flows · `extension/entry.tsx`
- [Extension UI](https://github.com/anyproto/anytype-ts/blob/develop/extension/popup.tsx): extension surfaces · Popup, auth, iframe, and success views for browser integration · `extension/popup.tsx`
- [Native host](https://github.com/anyproto/anytype-ts/blob/develop/go/nativeMessagingHost.go): go bridge · Native messaging host used to connect the browser extension to the desktop app · `go/nativeMessagingHost.go`

### Workers

Offloaded rendering and compute tasks

- [Graph worker](https://github.com/anyproto/anytype-ts/blob/develop/src/ts/workers/pixi-worker-entry.ts): render worker · Offloads graph rendering and onboarding animation work · `src/ts/workers/pixi-worker-entry.ts`
- [PDF worker](https://github.com/anyproto/anytype-ts/blob/develop/dist/workers/pdf.worker.mjs): 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](https://github.com/anyproto/anytype-ts/blob/develop/dist/lib/json/generated/.gitignore): built assets · Committed generated bindings, locale data, and packaged runtime assets · `dist/lib/json/generated/.gitignore`
- [Build scripts](https://github.com/anyproto/anytype-ts/blob/develop/scripts/build-electron.js): generation and packaging · Proto generation, service registry generation, build orchestration, release notes, and packaging helpers · `scripts/build-electron.js`
- [Vite builds](https://github.com/anyproto/anytype-ts/blob/develop/vite.config.ts): bundler configs · Separate desktop, web, extension, and worker build pipelines · `vite.config.ts`

### Other components

- **Middleware engine**: external sync backend · External anytype-heart local-first data engine and sync/storage boundary

## Connections

- 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
