How litcu/logseq works
Project Core and Its Purpose
• Logseq is a privacy-focused, open-source knowledge management and collaboration platform.
• It is built using multiple technologies (e.g., Clojure/ClojureScript for the core logic, Electron for desktop, native mobile projects for Android and iOS, and TypeScript/React for some UI packages).
• It supports a plugin ecosystem and integrates various modules (e.g., graph parsing, publishing, database, and whiteboard functions).
Break Down the Main Components
a. Frontend/UI Layer:
– Located mainly in the “src/main/frontend” directory.
– Contains a rich set of UI components (editors, pages, dialogs, headers, sidebars, whiteboard components, etc.).
– Submodules include rendering, state management, event handlers, and extensions (e.g., for PDF, markdown, and whiteboard functionality).
– Also look at “packages/ui” which provides an additional, reusable UI library for plugins or modular parts of Logseq.
b. Backend / Core Application Layer:
– “src/electron” contains the Electron main process code. This part handles system-level tasks such as file synchronization, window management, and IPC.
– “src/main” also includes shared modules (such as core logic, plugin API, file sync, and database integration).
– The project uses a datascript-based database (see “src/main/frontend/db” and supporting query and migration files), which is key to storing and retrieving user data.
c. Modular Subsystems ("deps" folder and others):
– “deps/common”, “deps/db”, “deps/graph-parser”, “deps/publishing”, and “deps/shui” represent functional modules that act as libraries or plugins providing specific features. For example:
• Graph-parser: Parses and manages note graphs.
• Publishing: Provides export to various formats.
• Shui: Likely supports custom components or themes.
– These modules communicate with the core application, often through well-defined APIs.
d. Cross-Platform / Mobile Integration:
– The “android” and “ios” directories hold native code for mobile versions.
– They integrate with the main codebase (via capacitor configurations and shared business logic) to ensure consistent functionality on mobile platforms.
e. Plugin Ecosystem and External Libraries:
– “libs” contains a set of libraries (LSPlugin) used to manage and invoke plugin-specific functionality.
– “packages/amplify” and “packages/ui” provide additional frameworks or examples, indicating that extensibility is a first-class concern.
– Integration with external systems (e.g., through isomorphic-git and external plugin APIs) is also part of the system.
f. Additional Modules / Tools:
– “tldraw” directory: Contains integration with a whiteboard-like tool, complete with its own module hierarchy (React components, TypeScript code, build configs) to support spatial canvas interactions.
– Testing and development are handled in “e2e-tests”, “src/test”, and “scripts” directories for build, CI/CD, and version bumping.
Relationships and Data Flow
– Represent the interaction between the core database (using Datascript) and the frontend queries (for persisting and retrieving notes and metadata).
– Indicate the plugin system and libraries (“libs” and “packages”) as a separate but integrated layer that extends or customizes the core functionality.
– Include mobile-specific components with connection lines to the shared business logic and cross-platform backend modules.
– If applicable, include CI/CD/workflow elements (GitHub workflows, Dockerfile, and build scripts) as supporting infrastructure elements.
Architectural Patterns and Design Principles
– Modular architecture: All parts of the system (UI, backend, mobile, plugins) are separated into well-defined directories and components.
– Loose coupling: The dependency management (through “deps.edn”, “package.json”, etc.) and plugin API imply that modules are loosely coupled.
– Cross-platform support: The codebase implements a multi-platform approach to support desktop (Electron), web, and mobile (Android/iOS) within one repo.
– Separation of concerns: Code is isolated into UI (presentation), core (business logic and database), and infrastructure (file syncing, plugin handling) layers.