openpylon/README.md

<p align="center">
  <img src="src-tauri/icons/128x128.png" alt="OpenPylon" width="96" />
</p>

<h1 align="center">OpenPylon</h1>

<p align="center">
  <strong>A local-first Kanban board for people who want to own their work.</strong>
  <br />
  No accounts. No cloud. No telemetry. No landlords between you and your data.
</p>

<p align="center">
  <img src="https://img.shields.io/badge/license-CC0_1.0-blue" alt="License: CC0 1.0" />
  <img src="https://img.shields.io/badge/version-0.1.0-green" alt="Version 0.1.0" />
  <img src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey" alt="Platforms" />
  <img src="https://img.shields.io/badge/built%20with-Tauri%20v2-orange" alt="Built with Tauri v2" />
</p>

---

## 🏴 Why OpenPylon?

Your productivity tools shouldn't phone home. They shouldn't harvest your habits. They shouldn't stop working when a company pivots to AI or gets acqui-hired.

OpenPylon is a desktop Kanban application that keeps everything on your machine. Every board, card, and attachment is a plain JSON file in a folder next to the executable. Copy it to a USB drive. Back it up to a NAS. Share it with your team over a local network. The data is yours — always has been, always will be.

No subscription. No signup. No server between you and your work.

**Built for people, not for platforms.**

---

## ✨ Features

### 📋 Boards

- **Unlimited boards** with custom accent colors and editable titles
- **Three built-in templates** — Blank, Kanban (To Do / In Progress / Done), and Sprint (Backlog / To Do / In Progress / Review / Done)
- **Save any board as a reusable template** — build your own workflows and share them freely
- **Duplicate entire boards** with all cards, labels, and settings preserved
- **Drag-and-drop reordering** in the board list
- **Sort boards** by name, last modified, date created, or manual drag order
- **Import and export** — JSON (full fidelity) and CSV (spreadsheet-compatible); imports from Trello JSON too

### 🏛️ Columns

- **Add, rename, reorder, and delete** columns with drag-and-drop
- **Three column widths** — Narrow, Standard, Wide
- **Column colors** — 10 preset hues or no color
- **WIP limits** — optional per-column capacity limits (3, 5, 7, or 10) with amber/red header warnings when the collective workload exceeds what's sustainable
- **Collapse columns** to a narrow vertical strip showing just the title and card count — keep things tidy without losing context

### 🃏 Cards

- **Drag-and-drop** cards within and between columns
- **Markdown descriptions** — full GitHub Flavored Markdown with tables, strikethrough, task lists, autolinks, and a live preview toggle
- **Checklists** — add items, check them off, reorder by dragging, track progress with a visual bar
- **Labels** — create labels with custom names and colors, toggle them per card
- **Due dates** — custom calendar picker with relative time display ("in 3 days", "overdue by 2 days")
- **Priority levels** — None, Low, Medium, High, Urgent — each with a distinct color indicator visible on card thumbnails
- **Cover colors** — 10 preset hues rendered as a colored header bar on the card detail
- **File attachments** — link to files in place or copy them into the board's data directory; open in your system's default application
- **Comments** — timestamped notes on each card, newest first, with add and delete
- **Card duplication** — copy a card within its column
- **Card aging** — cards that haven't been touched in a while gradually fade, so you can see at a glance where work has stalled

### 🔍 Filtering and Search

- **Filter bar** (press `/`) — narrow down cards by text search, labels, due date status (overdue, today, this week, no date), and priority level
- **Command palette** (`Ctrl+K`) — fuzzy search across cards in the current board, across all boards, and quick access to app actions like creating a new board or toggling dark mode
- **Cross-board search** — find any card by title or description across every board you have

### ⌨️ Keyboard Navigation

Full keyboard-driven workflow. Vim-style or arrow keys — your choice.

| Shortcut | Action |
|---|---|
| `j` / `k` or `↓` / `↑` | Navigate between cards vertically |
| `h` / `l` or `←` / `→` | Navigate between columns |
| `Enter` | Open the focused card |
| `Escape` | Close modal / clear focus / cancel edit |
| `/` | Toggle filter bar |
| `Ctrl+K` | Open command palette |
| `Ctrl+Z` | Undo |
| `Ctrl+Shift+Z` | Redo |
| `?` | Show all keyboard shortcuts |

### 🎨 Appearance

- **Theme** — Light, Dark, or follow your system preference
- **Accent color** — 10 hues (Teal, Blue, Purple, Pink, Red, Orange, Yellow, Lime, Cyan, Slate) applied globally across the interface
- **UI zoom** — 75% to 150% in 5% increments
- **Density** — Compact, Comfortable, or Spacious — adjust how much breathing room the interface gets
- **Board backgrounds** — None, Dots, Grid, or Gradient pattern per board
- **Default column width** — configure what width new columns start at
- **Custom scrollbars** — themed scrollbars throughout, with auto-hide behavior
- **Smooth animations** — staggered entrances, layout transitions, and micro-interactions powered by Framer Motion, with full `prefers-reduced-motion` support

### 🛡️ Data Safety

Your work is protected by multiple layers of redundancy — because tools that lose your data don't deserve your trust.

- **Auto-save** — boards save automatically 500ms after every change
- **Automatic backups** — timestamped snapshots every 5 minutes, last 10 retained per board
- **Version history** — browse and restore previous versions from the board settings menu
- **Rolling backup** — the previous save is always preserved as a `.backup.json` file
- **Portable storage** — all data lives in a `data/` folder next to the executable; no registry entries, no AppData, no hidden folders
- **Schema validation** — all data is validated with Zod on every load, with graceful fallback to defaults if a file is corrupted. Forward-compatible: boards from older versions just work.

### 🖥️ Desktop Integration

- **Custom frameless window** — integrated title bar with minimize, maximize, and close controls, plus a drag region that feels native
- **Window state persistence** — remembers your window position, size, and maximized state between sessions
- **Due date notifications** — OS-level desktop notifications for cards that are due today or overdue, checked hourly
- **Open attachments** directly in your system's default application
- **Right-click context menus** — on boards (duplicate, export, save as template, delete) and on cards (move, duplicate, set priority, delete)

---

## 📥 Installation

### Download

Grab the latest release from the [Releases](https://github.com/nicepylon/openpylon/releases) page.

| Platform | Format | Notes |
|---|---|---|
| Windows | `.exe` (portable) | Just unzip and run. No installer needed. |
| Windows | `.msi` / `.exe` (installer) | Traditional install if you prefer it. |
| macOS | `.dmg` | Drag to Applications. |
| Linux | `.AppImage` / `.deb` | AppImage runs anywhere; .deb for Debian/Ubuntu. |

### Build from Source

Anyone can build this. The source is yours.

**Prerequisites:**

- [Node.js](https://nodejs.org/) 18+
- [Rust](https://rustup.rs/) (latest stable)
- Platform-specific dependencies per the [Tauri v2 docs](https://v2.tauri.app/start/prerequisites/)

```bash
# Clone
git clone https://github.com/nicepylon/openpylon.git
cd openpylon

# Install dependencies
npm install

# Development (hot reload)
npm run tauri dev

# Production build
npm run tauri build
```

The compiled binary lands in `src-tauri/target/release/`. Installers (MSI, NSIS, etc.) appear in `src-tauri/target/release/bundle/`.

---

## 📂 Data Storage

Everything lives next to the executable. No cloud. No hidden directories. Just files you can see, copy, and control.

```
openpylon.exe
data/
├── settings.json                    # App preferences
├── boards/
│   ├── 01HXR5K9N2...json           # Each board is one JSON file
│   └── ...
├── templates/
│   ├── 01HXR7M3P4...json           # Saved board templates
│   └── ...
├── backups/
│   └── 01HXR5K9N2.../
│       ├── 01HXR5K9N2.1708123456.json
│       ├── 01HXR5K9N2.1708123756.json
│       └── ...                      # Timestamped snapshots (last 10 kept)
└── attachments/
    └── 01HXR5K9N2.../
        ├── diagram.png
        └── ...                      # Copied attachments per board
```

### 📄 Board Format

Each board is a self-contained JSON file with a Zod-validated schema. New fields added in future versions receive sensible defaults on load — so older board files never break. You can read, edit, or script against these files with any tool you like. They're just JSON.

### 🔄 Backup and Recovery

If something goes wrong:

1. **Version History** — open board settings (⚙️ icon in the top bar) → "Version History" → pick a snapshot → restore. Your current state is backed up first.
2. **Manual `.backup.json`** — every board has a `.backup.json` sibling in the `boards/` folder. Rename it to replace the current file.
3. **Timestamped snapshots** — find the one you want in `data/backups/<board-id>/` and copy it into `data/boards/`.

---

## 🔄 Import and Export

### Importing

Click the **Import** button on the board list screen and pick a `.json` file. OpenPylon auto-detects the format:

| Format | What Gets Imported |
|---|---|
| **OpenPylon JSON** | Everything — full fidelity round-trip, no data loss |
| **Trello JSON** | Lists → columns, cards, labels (with color mapping), checklists. Archived/closed items are skipped. |

Migrating off Trello? Export your board from Trello (Menu → Share → Export as JSON), then import it here. Your data belongs with you.

### Exporting

Right-click any board card on the board list to export:

| Format | Use Case |
|---|---|
| **JSON** | Full board data. Re-importable into OpenPylon or parseable by any tool. |
| **CSV** | Flat table with board name, column, title, description, labels, due date, checklist progress, and timestamps. Opens in Excel, Sheets, LibreOffice, or anything that reads CSV. |

No lock-in. Take your data wherever you want, whenever you want.

---

## ⚙️ Settings Reference

### Global Settings

| Setting | Options | Default |
|---|---|---|
| 🎨 Theme | Light · Dark · System | System |
| 🎯 Accent Color | Teal · Blue · Purple · Pink · Red · Orange · Yellow · Lime · Cyan · Slate | Teal |
| 🔎 UI Zoom | 75% – 150% (5% steps) | 100% |
| 📐 Density | Compact · Comfortable · Spacious | Comfortable |
| 📏 Default Column Width | Narrow · Standard · Wide | Standard |
| 🗂️ Board Sort Order | Manual · Name · Created · Modified | Modified |

### Per-Board Settings

| Setting | Options | Default |
|---|---|---|
| 🖼️ Background | None · Dots · Grid · Gradient | None |
| 📎 Attachment Mode | Link to original · Copy into board | Link |

### Per-Column Settings

| Setting | Options |
|---|---|
| 📏 Width | Narrow · Standard · Wide |
| 🎨 Color | 10 hues or None |
| 🚦 WIP Limit | None · 3 · 5 · 7 · 10 |
| 📌 Collapsed | Toggle on/off |

---

## 🛠️ Tech Stack

| Layer | Technology |
|---|---|
| 🦀 Runtime | [Tauri v2](https://v2.tauri.app/) — lightweight, native, no Electron bloat |
| ⚛️ Frontend | [React 19](https://react.dev/) + [TypeScript 5.8](https://www.typescriptlang.org/) |
| 🎨 Styling | [Tailwind CSS 4](https://tailwindcss.com/) + [Radix UI](https://www.radix-ui.com/) primitives |
| 🧠 State | [Zustand 5](https://zustand.docs.pmnd.rs/) + [Zundo](https://github.com/charkour/zundo) (50-step undo/redo) |
| 🖱️ Drag & Drop | [dnd-kit](https://dndkit.com/) |
| 🎬 Animation | [Framer Motion](https://www.framer.com/motion/) |
| ✅ Validation | [Zod](https://zod.dev/) |
| 🔣 Icons | [Lucide](https://lucide.dev/) |
| 📝 Markdown | [react-markdown](https://github.com/remarkjs/react-markdown) + [remark-gfm](https://github.com/remarkjs/remark-gfm) |
| 📜 Scrollbars | [OverlayScrollbars](https://kingsora.github.io/OverlayScrollbars/) |
| 🔤 Typography | [Epilogue](https://fonts.google.com/specimen/Epilogue) · [Instrument Serif](https://fonts.google.com/specimen/Instrument+Serif) · [Space Mono](https://fonts.google.com/specimen/Space+Mono) |

---

## 📁 Project Structure

```
openpylon/
├── src/                              # React frontend
│   ├── components/
│   │   ├── board/                    # Board view — columns, cards, filter bar, drag overlays
│   │   ├── boards/                   # Board list — grid, new board dialog, board cards
│   │   ├── card-detail/              # Card modal — markdown, checklists, labels, priority,
│   │   │                             #   due dates, attachments, comments, cover colors
│   │   ├── command-palette/          # Ctrl+K fuzzy search across everything
│   │   ├── import-export/            # Import/export buttons and file handling
│   │   ├── layout/                   # Top bar, window controls, frameless chrome
│   │   ├── settings/                 # Settings dialog with tabs
│   │   └── ui/                       # Shared primitives (button, dialog, tooltip, popover…)
│   ├── hooks/                        # Keyboard shortcuts, keyboard card navigation
│   ├── lib/                          # Storage, import/export, board factory, motion presets
│   ├── stores/                       # Zustand — app store, board store, toast store
│   └── types/                        # TypeScript interfaces and type definitions
├── src-tauri/                        # Tauri / Rust backend
│   ├── src/
│   │   ├── lib.rs                    # Plugin registration, portable data dir command
│   │   └── main.rs                   # Entry point
│   ├── capabilities/                 # Tauri security permissions
│   ├── icons/                        # App icons (ICO, ICNS, PNG)
│   ├── Cargo.toml                    # Rust dependencies
│   └── tauri.conf.json               # Tauri app configuration
├── docs/plans/                       # Design documents and implementation plans
├── package.json
└── README.md                         # You are here
```

---

## 🧑‍💻 Development

```bash
# Start dev server with hot reload (Vite + Cargo watch)
npm run tauri dev

# Type-check the frontend
npx tsc --noEmit

# Production build (exe + installers)
npm run tauri build
```

The dev server runs on `http://localhost:1420` with Vite HMR. Rust backend changes trigger automatic recompilation through Cargo watch.

### Contributing

OpenPylon is released into the public domain under CC0 1.0. There's no CLA, no copyright assignment, no gatekeeping. If you want to contribute, just open a PR. If you want to fork it and build something entirely different, go ahead — no permission needed.

Good things happen when tools are shared freely.

---

## 📄 License

<p align="center">
  <a href="https://creativecommons.org/publicdomain/zero/1.0/">
    <img src="https://licensebuttons.net/p/zero/1.0/88x31.png" alt="CC0 1.0" />
  </a>
</p>

**CC0 1.0 Universal — Public Domain Dedication**

To the extent possible under law, the authors of OpenPylon have waived all copyright and related rights to this software. This work is published from the United States.

You can copy, modify, distribute, and use this software — even for commercial purposes — without asking permission and without owing anyone anything.

See [LICENSE](LICENSE) or https://creativecommons.org/publicdomain/zero/1.0/ for details.

---

<p align="center">
  <sub>
    Made with care. Shared without conditions.
    <br />
    Your tools should serve you — not the other way around.
  </sub>
</p>