---
id: index
title: Core Concepts
sidebar_position: 1
---

# Core Concepts

Understanding the fundamental concepts behind beads.

## Design Philosophy

Beads was built with these principles:

1. **Git as source of truth** - Issues sync via JSONL files, enabling collaboration across branches
2. **AI-native workflows** - Hash-based IDs, JSON output, dependency-aware execution
3. **Local-first operation** - SQLite database for fast queries, background sync
4. **Declarative workflows** - Formulas define repeatable patterns

## Key Components

### Issues

Work items with:
- **ID** - Hash-based (e.g., `bd-a1b2`) or hierarchical (e.g., `bd-a1b2.1`)
- **Type** - `bug`, `feature`, `task`, `epic`, `chore`
- **Priority** - 0 (critical) to 4 (backlog)
- **Status** - `open`, `in_progress`, `closed`
- **Labels** - Flexible tagging
- **Dependencies** - Blocking relationships

### Dependencies

Four types of relationships:

| Type | Description | Affects Ready Queue |
|------|-------------|---------------------|
| `blocks` | Hard dependency (X blocks Y) | Yes |
| `parent-child` | Epic/subtask relationship | No |
| `discovered-from` | Track issues found during work | No |
| `related` | Soft relationship | No |

### Daemon

Background process per workspace:
- Auto-starts on first command
- Handles auto-sync with 5s debounce
- Socket at `.beads/bd.sock`
- Manage with `bd daemons` commands

### JSONL Sync

The synchronization mechanism:

```
SQLite DB (.beads/beads.db)
    ↕ auto-sync
JSONL (.beads/issues.jsonl)
    ↕ git
Remote repository
```

### Formulas

Declarative workflow templates:
- Define steps with dependencies
- Variable substitution
- Gates for async coordination
- Aspect-oriented transformations

## Navigation

- [Issues & Dependencies](/core-concepts/issues)
- [Daemon Architecture](/core-concepts/daemon)
- [JSONL Sync](/core-concepts/jsonl-sync)
- [Hash-based IDs](/core-concepts/hash-ids)