How to Contribute to the Tolaria Project: A Complete Guide for Developers

To contribute to the Tolaria project, fork the repository, configure the Tauri v2 and React development environment using pnpm install and cargo build, write tests with Vitest or Playwright, and submit focused PRs that pass the automated CodeScene health gate and pre-push hooks.

Tolaria is an open-source personal knowledge management desktop application built with a Tauri v2 backend (Rust) and a React with TypeScript frontend. When you contribute to the Tolaria project, you are working with a unique three-layer architecture that treats Markdown files on disk as the single source of truth. Understanding this disk-first philosophy and the repository's strict code-health automation is essential before modifying any behavior.

Prerequisites and Development Setup

Before writing code, ensure you have Node.js (with pnpm), Rust, and Cargo installed locally. The project uses a unified toolchain where the frontend and backend must compile together.

Initialize the environment with the following commands:

# Install frontend dependencies

pnpm install

# Build the Rust backend

cargo build

To launch the development server and verify your setup, run the UI on port 5201 as specified in AGENTS.md【L31-L37】:

pnpm dev --port 5201

This starts the Vite dev server and the Tauri window, enabling hot-reload for both the React frontend and Rust backend.

Understanding the Tolaria Architecture

Tolaria implements a strict three-layer data flow that you must respect when contributing changes:

1. Filesystem – Raw .md files stored on disk (src-tauri/src/vault/…).
2. Cache – A JSON index stored under ~/.laputa/cache/ and managed in src-tauri/src/vault/cache.rs.
3. React state – In-memory VaultEntry[] arrays consumed by the UI (src/lib/...).

The architecture follows a disk-first rule: all writes must hit the filesystem before the React state updates, and the cache is treated as disposable (it can be rebuilt from disk at any time). Review docs/ARCHITECTURE.md before modifying vault operations to ensure you do not violate these invariants.

The Contribution Workflow

Tolaria follows a lightweight, single-branch workflow enforced by Git hooks. All work is done on main, and the repository rejects pushes from other branches.

Step-by-Step Process

Follow this sequence derived from CONTRIBUTING.md and AGENTS.md:

1. Open an issue – File bugs via GitHub Issues and feature ideas via Canny to discuss intent before coding【L5-L13】.
2. Fork and clone – Create your fork and clone it locally.
3. Write a failing test – Capture intended behavior first using Vitest (TypeScript unit tests) or Playwright (end-to-end UI tests)【L68-L71】.
4. Implement the change – Keep pull requests small and focused; avoid unrelated refactors.
5. Commit with conventional prefixes – Use feat:, fix:, refactor:, test:, or docs: prefixes. Do not use --no-verify to bypass hooks【L22-L25】.
6. Push to main – The pre-push hook automatically runs linting, TypeScript compilation, the full test suite, and the CodeScene gate【L64-L66】.

If the pre-push hook blocks your commit due to failing health checks, refactor the code to resolve hotspots rather than lowering thresholds.

Code Quality Standards and UI Patterns

Tolaria enforces strict component usage and code health metrics through automated gates.

UI Component Requirements

Always use existing shadcn/ui components (e.g., Button, Input, Dialog) located in src/components/. Never use raw HTML elements like <button> or <input> directly【AGENTS.md†L39-L55】.

For example, when adding a "Refresh Vault" button to the sidebar in src/components/SidebarRefresh.tsx:

import { Button } from "@/components/ui/button";
import { RefreshCcw } from "lucide-react";
import { useVaultActions } from "@/hooks/useVaultActions";

export function SidebarRefresh() {
  const { reloadVault } = useVaultActions();

  return (
    <Button
      variant="ghost"
      size="sm"
      onClick={reloadVault}
      aria-label="Refresh vault"
    >
      <RefreshCcw className="mr-2 h-4 w-4" />
      Refresh
    </Button>
  );
}

CodeScene Health Gates

Every modified file must retain or improve its CodeScene health score. The repository uses ratcheted thresholds defined in .codescene-thresholds that are enforced during the pre-push hook【AGENTS.md†L92-L103】. If you introduce complexity hotspots, you must refactor them before the push will succeed.

Testing Your Changes

The project requires comprehensive test coverage using two frameworks:

• Vitest – For unit testing TypeScript logic and React hooks.
• Playwright – For end-to-end testing of the Tauri desktop window.

When adding the sidebar refresh button above, include a corresponding Playwright test in tests/smoke/sidebar-refresh.spec.ts:

import { test, expect } from "@playwright/test";

test("sidebar refresh button triggers vault reload", async ({ page }) => {
  await page.goto("http://localhost:5201");
  await page.getByRole("button", { name: "Refresh" }).click();
  await expect(page.locator("[data-testid=reload-spinner]")).toBeVisible();
  await expect(page.locator("[data-testid=reload-spinner]")).toBeHidden();
});

Tag smoke tests with @smoke so they run in the core regression suite.

Localization and Documentation

All user-visible strings must be externalized for i18n support. Add new text to src/lib/locales/en.json, then reference it through the runtime loader in src/lib/i18n.ts. Never hardcode English strings directly in components.

Additionally, update docs/ARCHITECTURE.md and docs/ABSTRACTIONS.md whenever you add public APIs or modify the data flow.

Key Files Every Contributor Should Know

Understanding these entry points accelerates onboarding:

• docs/ARCHITECTURE.md – High-level system diagram and data flow documentation.
• CONTRIBUTING.md – Official contribution policies and PR etiquette.
• AGENTS.md – Internal task workflow, UI standards, and code-health rules.
• src-tauri/src/vault/cache.rs – Cache implementation that accelerates vault scans.
• src-tauri/src/vault/watcher.rs – Filesystem watcher emitting vault-changed events.
• src/App.tsx – Entry point orchestrating the main window layout.
• src-tauri/src/ai_agents.rs – Backend glue for AI-agent panel and MCP integration.

Summary

• Set up the environment by running pnpm install and cargo build, then launch with pnpm dev --port 5201.
• Respect the architecture – Maintain the three-layer flow (filesystem → cache → React state) and the disk-first rule when working in src-tauri/src/vault/.
• Test first – Write Vitest unit tests or Playwright e2e specs before implementing features.
• Follow UI standards – Use shadcn/ui components exclusively and maintain CodeScene health scores above ratcheted thresholds.
• Commit cleanly – Use conventional prefixes (feat:, fix:), keep changes atomic, and let the pre-push hooks verify quality automatically.

Frequently Asked Questions

Do I need to know Rust to contribute to the Tolaria project?

While the backend uses Tauri v2 (Rust), many contributions can focus solely on the React/TypeScript frontend. However, any changes to vault operations—such as modifying src-tauri/src/vault/cache.rs or src-tauri/src/vault/watcher.rs—require Rust knowledge to handle the filesystem and JSON indexing logic safely.

Why does my push get rejected by the pre-push hook?

The hook enforces linting, TypeScript compilation (npx tsc --noEmit), Vitest unit tests, and CodeScene analysis【AGENTS.md†L106-L110】. If your code introduces complexity hotspots that fall below the thresholds in .codescene-thresholds, or if any tests fail, the push is blocked until you resolve the issues or refactor the hotspot.

Can I create a feature branch instead of working on main?

No. The repository enforces a single-branch workflow where all contributions must remain on the main branch. The tooling explicitly rejects pushes from other branches to maintain a linear history and simplify the CodeScene ratcheting process.

How do I add new user-facing text or labels?

All visible strings must be added to src/lib/locales/en.json first, then accessed via the i18n system defined in src/lib/i18n.ts. Hardcoding strings directly into components violates the localization standards and will fail code review.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}