# Personal Backlog

A minimalist, single-user task manager where **a single Markdown file is your database**.

No cloud. No accounts. No vendor lock-in. Your tasks live in a plain `backlog.md` file you can read, edit, and version-control with any tool you already use.

## Why Not Just Use...

| Concern | Todoist / TickTick / Notion | This App |
|---------|-----------------------------|----------|
| Where's my data? | Their servers | A single `.md` file on *your* disk |
| Online required? | Yes (cloud sync) | Never — even the server is localhost-only |
| Vendor lock-in? | You need their app to read your data | It's a `.md` file — read it in VS Code, Vim, `cat` |
| Can I `git commit` my tasks? | No | Yes — it's a text file |
| Can I sync across devices? | Built-in cloud | Any file sync — Dropbox, rsync, git, USB, anything |
| Price | $5–6/mo | Free, forever |

**If you've ever wanted your task list to be just a file — this is it.**

## Quick Start

### Option A: Python Server (all browsers)

Works with Chrome, Firefox, Safari — any browser. The server is a single Python file with zero dependencies.

```bash
cd personal-backlog
python3 server/server.py --port 8080
```

Then open **http://localhost:8080** in your browser.

The server creates `backlog.md`, `backups/`, and `stats.jsonl` in its own directory by default. To store data elsewhere:

```bash
python3 server/server.py --port 8080 --dir ~/my-backlog
```

### Option B: Standalone HTML (Chrome / Edge only)

No Python needed. Just open the HTML file:

```bash
open webapp/index-style-v2.html
```

Or serve it with any static file server:

```bash
cd webapp && python3 -m http.server 3000
# Then open http://localhost:3000/index-style-v2.html
```

On first launch, the browser will prompt you to **select a folder**. This is required because browsers can't access your filesystem without explicit permission. Create a folder (or pick an existing one) and the app will create `backlog.md`, `backups/`, and `stats.jsonl` inside it.

## How It Works

### The Markdown File

All your tasks live in `backlog.md`, structured as:

```markdown
# Backlog

<!-- SECTION: ENTRIES -->

- [ ] [P0] Ship landing page *(due: 2025-06-01, priority: P0, progress: 50)*
  - [x] Design mockups *(priority: P0, progress: 100)*
  - [/] Implement frontend *(priority: P1, progress: 30)*
- [!] [P1] API integration *(priority: P1, reason: waiting for keys)*
- [>] [P2] Blog post *(priority: P2, due: 2025-07-15)*

<!-- SECTION: HISTORY -->

| Timestamp | Item ID | Action | Details |
|-----------|---------|--------|---------|
| 2025-05-10T14:32:00Z | i-m1 | status_changed | open → done |

<!-- SECTION: INTEGRITY -->

<!-- saved: 2025-05-10T14:35:12Z | checksum: sha256:abc123... | entries: 3 | history: 1 -->
```

You can edit this file in any text editor. The app detects external changes and reloads automatically.

### Features

- **4-level nesting** — Area → Project → Task → Sub-task
- **6 statuses** — open, in-progress (`/`), blocked (`!`), postponed (`>`), done (`x`), cancelled (`-`)
- **Priorities** — P0 (burning) through P3, with drag-and-drop reordering within each priority
- **Progress tracking** — 0–100% per task; done auto-sets to 100%
- **Due dates** — with overdue highlighting
- **Tags** — free-form labels with autocomplete
- **Quick search** — instant text search with hierarchical parent visibility
- **Integrity checks** — SHA-256 checksum on every save; warning-only on mismatch
- **Automatic backups** — timestamped on every save, rotating retention
- **Stats & metrics** — items created/completed, avg time in-progress, most active project — all from real history data
- **Import/Export** — Markdown or JSON, with checksum validation
- **Admin page** — health monitoring, backup browser, stats overview, manual actions

## Two Storage Modes

The app detects which mode to use automatically:

| | API Server | Direct File Access |
|---|---|---|
| **How to start** | Run `python3 server/server.py` | Open `webapp/index-style-v2.html` in Chrome/Edge |
| **Works in** | Any browser | Chrome, Edge only |
| **File access via** | HTTP REST API | File System Access API |
| **Folder picker** | Not needed | Required on first launch |
| **LAN access** | Yes (phone, tablet) | No (local browser only) |
| **Admin shows paths** | Yes (full path) | Folder name only |

### Why the Folder Picker? (Direct Mode)

When you open the HTML file directly, the browser has no access to your filesystem. The **File System Access API** (`showDirectoryPicker()`) is the only way to read and write local files from a web page. You grant permission once; the handle is stored in IndexedDB so it persists across reloads.

**To reset the folder** (pick a different one or clear saved permissions):

1. Open DevTools → Application → IndexedDB → delete the `pb-storage-v2` database
2. Reload the page — you'll be prompted to pick a folder again

## Coherency Between Python and Standalone Versions

Both versions read and write the **exact same `backlog.md` format**. The Parser and Serializer are identical in logic. This means you can:

1. **Start with the Python server** — add tasks, create structure
2. **Shut down the server** — open the same `backlog.md` location via the standalone HTML
3. **Switch freely** — edits in one mode are visible in the other

### How to Switch Modes

**From API server to standalone:**

1. Stop the server (`Ctrl+C`)
2. Open `webapp/index-style-v2.html` in Chrome/Edge
3. When prompted, select the folder that contains your `backlog.md` (e.g. the `server/` directory or wherever `--dir` pointed)

**From standalone to API server:**

1. Note which folder your `backlog.md` lives in
2. Start the server pointing to that folder:
   ```bash
   python3 server/server.py --dir /path/to/your/folder
   ```
3. Open `http://localhost:8080`

### Important Notes

- **Don't run both modes simultaneously** against the same `backlog.md` — the last writer wins and you may lose edits.
- **External edits** (Vim, VS Code, etc.) are detected automatically via checksum polling every 5 seconds. If you have unsaved changes in the app, you'll get a conflict resolution dialog.
- The **checksum is a save indicator**, not a gate. If it mismatches (e.g. you edited the file by hand), the app still loads it — just with a yellow warning banner. The next save recalculates a correct checksum.

## Project Structure

```
personal-backlog/
├── README.md
├── doc/
│   ├── requirements/requirements.md      # Functional & non-functional requirements
│   └── architecture/
│       ├── architecture.md               # High-level architecture
│       └── tdd.md                        # Technical Design Document
├── server/
│   ├── server.py                         # Python REST API server (~420 LoC, stdlib only)
│   ├── backlog.md                        # Master data file (created on first run)
│   ├── backups/                          # Automatic timestamped backups
│   └── stats.jsonl                       # Append-only analytics log
├── web/                                  # V2 source code (React 18 + JSX) + build tooling
│   ├── index.html                        # Dev entry point (React + Babel from CDN)
│   ├── styles.css                        # All CSS
│   ├── storage.jsx                       # Parser, ApiBackend, DirectBackend, SyncPoller
│   ├── helpers.jsx                       # Utility functions, event handling
│   ├── app.jsx                           # Root App component, state, save/load lifecycle
│   ├── tree.jsx                          # Task tree rendering
│   ├── dialogs.jsx                       # Modal dialogs
│   ├── admin.jsx                         # Admin dashboard
│   ├── filter-panel.jsx                  # Filter sidebar
│   ├── tweaks-panel.jsx                  # Settings panel
│   ├── data.jsx                          # Seed data (test-only, not loaded by default)
│   ├── bundle.js                         # Build tool: multi-file JSX → single HTML
│   ├── package.json                      # @babel/core + @babel/preset-react
│   └── node_modules/
├── webapp/                               # Built output — ready to open or deploy
│   └── index-style-v2.html              # Self-contained single-file SPA (~348 KB)
```

## Development

### Running the Dev Server (in-browser Babel)

```bash
cd web
python3 -m http.server 9000
# Open http://localhost:9000 — React + Babel load from CDN, no build step needed
```

### Building the Production Bundle

```bash
cd web
npm install          # once, to install @babel/core + @babel/preset-react
node bundle.js index.html ../webapp/index-style-v2.html
```

The bundler pre-compiles all JSX, swaps React dev CDN builds for production minified builds, removes Babel entirely, and writes a single self-contained HTML file to `webapp/`.

See [`doc/architecture/tdd.md`](doc/architecture/tdd.md) for full technical details.

### Requirements

- **Runtime**: Python 3.8+ (server), any modern browser
- **Development**: Node.js 18+ (for the bundler only)
- **Bundler deps**: `cd web && npm install`

## License

Personal use. Do whatever you want with it.