Repository Guidelines

Project Structure & Module Organization

src/ is the main codebase.
- src/main/ contains core application logic.
- src/main/mobile/ is the mobile app code.
- src/main/frontend/components/ houses UI components.
- src/main/frontend/inference_worker/ and src/main/frontend/worker/ hold webworker code, including RTC in src/main/frontend/worker/rtc/.
src/electron/ is Electron-specific code.
src/test/ contains unit tests.
deps/ contains internal dependencies/modules.
clj-e2e/ contains app end-to-end tests (Playwright + Clojure test runner).
cli-e2e/ contains shell-first end-to-end tests for compiled logseq-cli and db-worker-node.

bb dev:lint-and-test runs linters and unit tests.
bb dev:test -v <namespace/testcase-name> runs a single unit test (example: bb dev:test -v logseq.some-test/foo).
App E2E tests live in clj-e2e/; run from that directory with bb test (or bb -f clj-e2e/bb.edn test from repo root).
CLI E2E tests live in cli-e2e/; run with bb -f cli-e2e/bb.edn test --skip-build (or bb -f cli-e2e/bb.edn build first when needed).
If a request says only “e2e”, clarify whether it targets clj-e2e/ or cli-e2e/ before planning changes.

ClojureScript keywords are defined via logseq.common.defkeywords/defkeyword; use existing keywords and add new ones in the shared definitions.
Follow existing namespace and file layout; keep related workers and RTC code in their dedicated directories.
Prefer concise, imperative commit subjects aligned with existing history (examples: fix: download, enhance(rtc): ...).
Clojure map keyword name should prefer - instead of _, e.g. :user-id instead of :user_id.

Unit tests live in src/test/ and should be runnable via bb dev:lint-and-test.
Name tests after their namespaces; use -v to target a specific test case.
Run lint/tests before submitting PRs; keep changes green.

Commit subjects are short and imperative; optional scope prefixes appear (e.g., fix: or enhance(rtc):).
PRs should describe the behavior change, link relevant issues, and note any test coverage added or skipped.

Review notes live in prompts/review.md; check them when preparing changes.
DB-sync feature guide for AI agents: docs/agent-guide/db-sync/db-sync-guide.md.
DB-sync protocol reference: docs/agent-guide/db-sync/protocol.md.
For db-sync D1 schema changes, add or update a Cloudflare worker SQL migration under deps/db-sync/worker/migrations/; do not rely on ad hoc runtime-only schema migration code.
New properties should be added to logseq.db.frontend.property/built-in-properties.
Avoid creating new class or property unless you have to.
Avoid shadow var, e.g. bytes should be named as payload.