Brittle — Literature Management System

A desktop application for managing academic references, PDFs, and annotations. Written in Rust.

Project Vision

Brittle is a personal literature management tool in the spirit of Zotero. Core capabilities:

Organize references in nested libraries (libraries contain sub-libraries)
Display and annotate PDFs (create, edit, view annotations)
Export references as BibTeX

This is a hobby project built primarily through AI-assisted development. The human operator makes architectural decisions; the agent writes the code.

Architecture

Mandatory: Library-First Design

The backend is a Rust crate (brittle-core) that exposes a public API. This is the primary interface. A frontend like iced links directly against this crate.

The API must be designed so that wrapping it in REST, gRPC, IPC, or any other transport layer requires zero changes to brittle-core. This means:

No UI concepts leak into the core (no widget types, no rendering logic, no event loops)
Return types must be transport-agnostic: no framework-specific channels, callbacks, or handle types. Plain data that any layer can serialize or forward
Errors are structured and meaningful, not stringly-typed
The public API surface is the single source of truth for what Brittle can do

If a frontend needs something that isn't in the core API, the correct response is to extend the core API — not to hack around it.

Dependency Philosophy

Use external crates where they provide real value (PDF rendering, BibTeX parsing, SQLite bindings, etc.). Do not pull in a dependency for something the standard library handles or for trivial utility code. When choosing between crates, prefer those that are well-maintained, have minimal transitive dependencies, and are widely used in the Rust ecosystem.

Database Versioning

The database must support some form of version control or change tracking. The specific mechanism (event sourcing, snapshot-based, migration-based, audit log, etc.) is an open design question to be resolved during planning before implementation begins.

Development Workflow

Every non-trivial feature follows this process end-to-end. Do not skip steps.

1. Requirements (what, not how)

Start from user-facing behavior. What does this feature need to do? Define concrete acceptance criteria. Do not think about implementation yet.

2. Architectural Fit

Before designing anything, assess how this feature relates to what already exists:

Fit: Does it integrate cleanly with the current structure?
Risk: If restructuring is needed, what existing functionality could break?
Benefit: What do we gain from restructuring vs. working within the current design?
Verdict: Restructure, adapt, or flag as tech debt?

Write this assessment as part of the plan. Do not silently restructure.

3. Design (top-down)

Now decide how: types, traits, modules, public API surface. Work downward from the API the feature needs, not upward from utility code you think might be useful.

4. Tests

Write failing tests that encode the acceptance criteria from step 1. These tests define "done."

5. Implementation

Make the tests pass. Then refactor with confidence.

Use Plan mode at the start of any multi-file task.

Agent Behavior

Do not blindly implement what is asked. Consider whether the request is actually what the user needs, whether there's a better approach, and whether there are edge cases or implications the user may not have considered.

If you see a better path, argue for it. Explain your reasoning clearly. But if the user disagrees after hearing your case, accept their decision and implement it well.

Code Style

Prioritize readability and testability over cleverness
Use meaningful names; avoid abbreviations unless they're domain-standard (e.g., bib, doi, pdf)
Keep functions focused — if a function needs a paragraph-long comment to explain, it should probably be split
Use Rust idioms: Result for fallible operations, strong types over stringly-typed data, enum for state machines
Run cargo clippy and cargo fmt before considering any task complete
Document public API items with doc comments

4.2 KiB Raw Blame History