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

> Learn how to contribute to the Tolaria project. Follow this guide to fork the repo, set up your dev environment, write tests, and submit PRs effectively.

- Repository: [Refactoring/tolaria](https://github.com/refactoringhq/tolaria)
- Tags: how-to-guide
- Published: 2026-05-04

---

**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:

```bash

# 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`](https://github.com/refactoringhq/tolaria/blob/main/AGENTS.md)【L31-L37】:

```bash
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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/CONTRIBUTING.md) and [`AGENTS.md`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/src/components/SidebarRefresh.tsx):

```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`](https://github.com/refactoringhq/tolaria/blob/main/tests/smoke/sidebar-refresh.spec.ts):

```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`](https://github.com/refactoringhq/tolaria/blob/main/src/lib/locales/en.json), then reference it through the runtime loader in [`src/lib/i18n.ts`](https://github.com/refactoringhq/tolaria/blob/main/src/lib/i18n.ts). Never hardcode English strings directly in components.

Additionally, update [`docs/ARCHITECTURE.md`](https://github.com/refactoringhq/tolaria/blob/main/docs/ARCHITECTURE.md) and [`docs/ABSTRACTIONS.md`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/docs/ARCHITECTURE.md)** – High-level system diagram and data flow documentation.
- **[`CONTRIBUTING.md`](https://github.com/refactoringhq/tolaria/blob/main/CONTRIBUTING.md)** – Official contribution policies and PR etiquette.
- **[`AGENTS.md`](https://github.com/refactoringhq/tolaria/blob/main/AGENTS.md)** – Internal task workflow, UI standards, and code-health rules.
- **[`src-tauri/src/vault/cache.rs`](https://github.com/refactoringhq/tolaria/blob/main/src-tauri/src/vault/cache.rs)** – Cache implementation that accelerates vault scans.
- **[`src-tauri/src/vault/watcher.rs`](https://github.com/refactoringhq/tolaria/blob/main/src-tauri/src/vault/watcher.rs)** – Filesystem watcher emitting `vault-changed` events.
- **[`src/App.tsx`](https://github.com/refactoringhq/tolaria/blob/main/src/App.tsx)** – Entry point orchestrating the main window layout.
- **[`src-tauri/src/ai_agents.rs`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/src-tauri/src/vault/cache.rs) or [`src-tauri/src/vault/watcher.rs`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/src/lib/locales/en.json) first, then accessed via the i18n system defined in [`src/lib/i18n.ts`](https://github.com/refactoringhq/tolaria/blob/main/src/lib/i18n.ts). Hardcoding strings directly into components violates the localization standards and will fail code review.