Joy DocsArchitecture
Joy's internal architecture - crate structure, data model, status workflow, and configuration.
Crate Structure
Joy is implemented in Rust as a set of crates within the joyint/joy repository. The joy-core library crate contains the shared logic. joy-cli is the binary; joy-ai and the chat crates are libraries that the CLI, the desktop app, and the platform share. joy-bi is a reports plugin.
What joy-core Provides
| Module | Purpose |
|---|---|
| Item model | Types, priorities, effort, tags, dependencies, parent-child relationships |
| YAML I/O | Read and write .joy/ files with validation |
| Status logic | State machine for item lifecycle |
| Event log | Append-only log of all actions for audit |
| Config system | Layered configuration with defaults, project, and personal overrides |
| Git integration | Commit detection, branch awareness, VCS abstraction |
| Auth and guard | Identity, delegation tokens, capabilities, and gate enforcement |
| Crypt | Zone keys and encryption of confidential items |
Data Model
The data model centers on the project, its items, and its milestones. A workspace is a conceptual grouping (a data container backed by a Git repo), not a stored entity, so it does not appear below.
An item can also reference other items directly: parent points to a parent item (epic or story), and deps lists items that must be done first. Both are item-to-item links and are not drawn as separate entities below.
Item Types
Every item has a type that describes what kind of work it represents:
| Type | Purpose |
|---|---|
| epic | Large body of work, contains child items |
| story | User-facing feature or change |
| task | Technical work, implementation step |
| bug | Defect to fix |
| rework | Improvement to existing code (refactor, cleanup) |
| decision | Architectural or process decision to document |
| idea | Captured thought, not yet committed to |
| job | Unit of AI work with a scope, a budget, and a time window |
Priority and Effort
Priority levels: extreme, critical, high, medium, low.
Effort uses a 1-7 scale: 1 = trivial, 2 = small, 3 = medium, 4 = large, 5 = major, 6 = heavy, 7 = massive.
Status Workflow
Items follow a small, defined lifecycle (new, open, in-progress, review, closed, deferred) with one-word verb shortcuts, and transitions can be tightened with gates. See the Workflow page for the states, verbs, gates, and the full diagram.
Config Layering
Joy uses a layered configuration system. Each layer overrides the previous one, so project settings can override defaults, and personal preferences can override project settings.
How Layering Works
- Code defaults - Hard-coded values in
joy-core. Always present, always reasonable. - config.defaults.yaml - The project's shared defaults in
.joy/, committed so the whole team gets them. - Global config - User-level settings in
~/.config/joy/config.yaml. Apply to every project. - Personal project config - Your own overrides for this project in
.joy/config.yaml. The file is gitignored and stays on your machine.
Each layer only needs to specify the values it wants to override. Everything else falls through to the layer below.