README.md

Pomotoro Documentation

Reference index for the Pomotoro codebase — a native Pomodoro focus timer built with Rust + Tauri on Clean Architecture + DDD. For the project pitch and end-user info, see the root README. For why the project exists, see MOTIVATION.md.

Start here

• Getting Started — set up your environment and make your first change.
• Architecture Overview — the four layers and the dependency rule.

Architecture — understand the system

How the codebase is structured and how data moves through it.

• Overview — Clean Architecture layers & tech stack
• Domain Layer — entities, value objects, aggregates, events
• Use Cases Layer — application services & DTOs
• Infrastructure Layer — adapters, SQLite repos, event bus
• Data Flow — tracing a request UI → Domain → persistence
• Event System — domain events, handlers, choreography
• Dependencies & Boundaries — the dependency rule, enforced

Reference — look things up

Precise, lookup-oriented material.

• Module Map — file-by-file tour of core/ + apps/
• API Index — key functions, traits, and Tauri commands
• Domain Model — entities, value objects, events, aggregate boundaries
• Feature docs — per-feature design notes
  • Screen Blocker
  • Task Reset

Standards — how we write code

Conventions every contribution should follow.

• Style Guide — the canonical development guidelines
• Naming Convention — context-aware, no-stutter naming
• File Structure — domain-centric file layout rules
• Code Templates — copy-paste entity / repository / use-case skeletons
• Domain Services — what they are and aren't
• Patterns — repository, builder, event-driven, DI, type-safety patterns

Workflows — how we do tasks

Step-by-step guides for common activities.

• Development Workflow — git branches, commits, CI, release process
• Releasing — cut a release, version bumping, recovery, how the pipeline is wired
• Adding a Feature — full Clean-Architecture feature walkthrough
• Fixing a Bug — reproduce → failing test → root cause → fix
• Testing — test pyramid, layer-specific tests, commands
• Code Review — PR template, review checklist, review levels

Quick reference

All build/test/dev commands run through just — run just with no arguments to see them all. The essentials:

just dev          # dev server (Vite + Tauri, hot-reload)
just test         # all workspace tests
just ci           # full gate: test, check, fmt, clippy, react lint+typecheck

Per-layer tests: just test-domain · just test-usecases · just test-infra. See the root README's Development section for the full command table and database-migration commands.