openpylon/README.md

🏗️ OpenPylon

A local-first Kanban board for people who want to own their work.
No accounts. No cloud. No telemetry. No landlords between you and your data.

---

🏴 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. No one profits from your productivity except you.

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

♿ Accessibility (WCAG 2.2 AAA)

OpenPylon targets WCAG 2.2 AAA conformance - because productivity tools should work for everyone, not just people with perfect vision and a mouse.

Color and Contrast

• 7:1 enhanced contrast on all text and interactive elements, in both light and dark themes
• 3:1 non-text contrast on borders, scrollbar thumbs, and focus indicators
• High-contrast mode support - prefers-contrast: more boosts all tokens further
• Color is never the sole indicator - priority levels, due date status, and labels all include text or shape cues alongside color

Focus and Keyboard

• 3px dual-ring focus indicators visible on every interactive element, against any background
• Skip-to-content link as the first focusable element on the page
• Full keyboard navigation - vim keys, arrow keys, tab order, Escape to dismiss
• Shift+F10 context menus - right-click menus are also reachable via keyboard
• Focus trapping in all modals and dialogs with focus restore on close
• Hidden interactive elements (menu buttons, action buttons) become visible on focus-visible, not just hover

Screen Readers and ARIA

• ARIA live regions announce card/column creation, deletion, moves, filter changes, and drag-and-drop operations
• Proper dialog semantics - role="dialog", aria-modal, aria-labelledby on all modals
• Tab/tabpanel pattern in settings with role="tablist", role="tab", aria-selected
• Calendar grid with role="grid", aria-selected on date cells, labeled navigation
• aria-label on every icon-only button, color swatch, status indicator, and unlabeled input
• aria-pressed on all toggle buttons (theme, density, motion, label chips, priority)
• Screen-reader-only labels for search inputs, select dropdowns, and range sliders

Toasts and Notifications

• 8-second auto-dismiss with pause-on-hover and pause-on-focus
• Visible dismiss button on every toast
• aria-live="polite" region so screen readers announce toast content without interrupting

Motion

• prefers-reduced-motion fully respected - both via CSS media query and an in-app toggle
• No essential information conveyed through animation alone

Page Structure

• Dynamic page titles - updates to reflect the current board name
• Landmark regions and semantic HTML throughout
• Minimum touch targets - 44px interactive area on small buttons via extended hit zones

🛡️ 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)

---

📥 Getting Started

Download

Grab openpylon.exe from the Releases page. That's it. Unzip, run, done.

No installer. No admin rights. No registry entries. Runs from anywhere - your desktop, a USB stick, a shared drive. Put it wherever you want. It's yours.

💡 Fully portable - OpenPylon stores all its data in a data/ folder right next to the executable. Move the folder, move your data. Delete the folder, it's gone. No traces left behind.

Build from Source

Anyone can build this. The source is yours to read, modify, and redistribute.

Prerequisites:

• Node.js 18+
• Rust (latest stable)
• Tauri v2 prerequisites for Windows

# Clone
git clone https://git.lashman.live/lashman/openpylon.git
cd openpylon

# Install dependencies
npm install

# Development (hot reload)
npm run tauri dev

# Production build
npm run tauri build

The portable executable lands in src-tauri/target/release/openpylon.exe.

---

📂 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. No proprietary formats, no binary blobs, no vendor lock-in.

🔄 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 - not with Atlassian.

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. We'd rather you have the freedom to leave than the obligation to stay.

---

⚙️ 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 - lightweight, native, no Electron bloat
⚛️ Frontend	React 19 + TypeScript 5.8
🎨 Styling	Tailwind CSS 4 + Radix UI primitives
🧠 State	Zustand 5 + Zundo (50-step undo/redo)
🖱️ Drag & Drop	dnd-kit
🎬 Animation	Framer Motion
✅ Validation	Zod
🔣 Icons	Lucide
📝 Markdown	react-markdown + remark-gfm
📜 Scrollbars	OverlayScrollbars
🔤 Typography	Epilogue · Instrument Serif · Space Mono

All dependencies are free and open-source. No proprietary tooling. No paid services. The entire stack can be audited, forked, and rebuilt by anyone.

---

📁 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
│   ├── 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

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

# Type-check the frontend
npx tsc -noEmit

# Production build (portable exe)
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

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 or https://creativecommons.org/publicdomain/zero/1.0/ for details.

---

_{Made with care. Shared without conditions.
Your tools should serve you - not the other way around.}