---

title: "Architecture" last_updated: 2026-03-21 #

System Overview #

Commonplace is a desktop app with:

• Frontend: React + TypeScript (src/)
• Backend: Tauri command layer (src-tauri/) + Rust workspace crates (crates/)

User-selected folders (locations) are the source of truth for document files. SQLite stores metadata, indexes, and settings.

Frontend #

Composition #

• Bootstrap happens in src/main.tsx.
• Routing lives in src/Router.tsx.
• The main window shell is src/App.tsx.
• The quick capture window is src/components/QuickCapture/QuickCaptureApp.tsx.

Controller Layer #

Frontend orchestration is split across focused hooks rather than a single app controller:

• src/hooks/controllers/useAppChromeController.ts
  • window chrome state such as theme and sidebar visibility
• src/hooks/controllers/useWorkspaceViewController.ts
  • workspace sync
  • session restore
  • editor state
  • preview state
  • export dialog wiring
  • diagnostics/help sheet routing
• src/hooks/controllers/useWorkspaceController.ts
  • locations, documents, tabs, sidebar refresh, file operations
• src/hooks/app/useSettingsSync.ts
  • backend settings hydration and persistence
  • sidebar tree hydration/persistence through sqlite-backed kv state

State #

• Runtime state is split across multiple Zustand stores under src/state/stores/.
• src/state/selectors.ts exposes focused hooks so presentational components do not bind directly to raw store modules.
• Current store modules are:
  • layout
  • workspace
  • tabs
  • pdf-export
  • text-export
  • docx-export
  • search
  • ui
  • shortcuts
  • toasts
• src/state/stores/app.ts is now a merged convenience facade used where a combined app shape is helpful, especially in tests and compatibility code.

Command Boundary #

• src/ports/ defines the frontend/backend command boundary.
• runCmd interprets typed commands (Invoke, Batch, watcher commands).
• Command builders centralize payload and callback shape for Tauri commands.

Backend #

Tauri Layer #

• src-tauri/src/lib.rs configures plugins and command handlers.
• AppState in src-tauri/src/commands.rs holds:
  • store: Arc<Store>
  • active filesystem watchers
• Commands cover locations, docs, search, markdown rendering, settings, session restore, and global capture.

Rust Workspace #

• crates/core: shared types and error contracts.
• crates/store: SQLite-backed persistence, indexing, save logic.
• crates/markdown: markdown render pipelines for preview and PDF AST.

Rendering Pipelines #

• Preview: frontend requests markdown_render, then renders returned HTML + metadata.
• PDF: frontend requests markdown_render_for_pdf, converts AST to PDF via @react-pdf/renderer, and writes bytes using Tauri plugins.
• DOCX: frontend requests markdown_render_for_docx, then writes returned bytes via Tauri plugins.
• Plaintext: frontend requests markdown_render_for_text, then writes plain text bytes via Tauri plugins.

Runtime Events #

Backend events (backend-event) are consumed by useBackendEvents.

Primary consumers:

• useWorkspaceSync for location refresh and filesystem change reactions
• BackendAlerts for surfaced UI warnings such as missing locations and conflicts