Para

A personal productivity web app based on the P.A.R.A. method - a system for organizing digital information designed by Tiago Forte.

About This Project

Para is both a functional productivity tool and an experiment in AI-assisted software development. The entire codebase is written by AI (Claude), guided by strict development rules and quality constraints defined in AGENTS.md.

The goal is to demonstrate that AI can produce production-quality code when given:

• Mandatory TDD - Tests must be written before implementation
• Mutation testing - No surviving mutants allowed (100% test effectiveness)
• Security checks - Brakeman, bundler-audit, and dependency audits on every change
• Strict linting - RuboCop with Rails omakase style
• Data isolation requirements - Users can only access their own data

This results in a codebase with comprehensive test coverage, no dead code, and verified security practices.

What is P.A.R.A.?

The P.A.R.A. method organizes all your digital information into four categories:

Category	Description
Project	Short-term efforts with a defined goal and deadline
Area	Ongoing areas of responsibility (family, health, job, finances)
Resource	Reference materials, files, and information for future use
Archive	Inactive items from any category, kept for reference

Items flow naturally between categories as their status changes - a Project becomes an Archive when completed, a Resource might become a Project when you decide to act on it.

Features

Organize with ParaItems

Each ParaItem represents a Project, Area, Resource, or archived item. The tab-based interface gives you instant access to all related content:

• Dashboard - Overview stats, upcoming tasks, and activity journal
• Tasks - Kanban board with drag-and-drop
• Explorer - Notes and files in a unified file-system view with folders
• Settings - Edit project details, manage collaborators, and public sharing

Upcoming Tasks

Both the global dashboard and each ParaItem dashboard show an "Upcoming Tasks" card:

• Tasks that are overdue, due today, or due within 3 days
• Excludes completed tasks
• Sorted by due date (earliest first)
• Overdue tasks highlighted in red
• Inline status dropdown for quick updates
• Click task title to view details

Tasks with Kanban Board

• Four columns: Todo, In Progress, Blocked, Done
• Drag-and-drop between columns
• Enhanced cards showing first tag (+N indicator), description preview, and due date
• Infinite sub-task nesting (tasks within tasks within tasks...)
• Due dates with visual indicators (overdue, due today, upcoming)
• File attachments and timestamped comments

Explorer - Unified File System

A Finder-style view combining notes and files in a single, organized interface:

• Nested folders - Unlimited folder depth for organization
• Mixed content - Notes and files together in any folder
• Drag and drop - Move items between folders with visual feedback
• Sorting options - Sort by name, date created, date modified, or type
• Keyboard navigation - Arrow keys, Enter, Backspace for fast navigation
• Mobile swipe actions - Swipe to delete, edit, or download
• Breadcrumb navigation - Click any level to jump back
• Folder sharing - Share entire folders publicly (read-only, recursive)

Rich Text Notes

• Full rich text editor (bold, italic, lists, links, etc.)
• Attach files directly within notes
• Organize in folders via Explorer

File Management

• Drag-and-drop uploads
• Organize in folders via Explorer
• Tag-based filtering
• Automatic metadata extraction

Activity Journal

• Automatic tracking of all activity (task created, completed, moved, etc.)
• Manual journal entries with rich text
• Inline editing of manual entries (pencil icon)
• Chronological feed per ParaItem and on the global dashboard

Quick Actions

• Set a default project for rapid capture
• Quick add buttons on dashboard for tasks, notes, and files
• Keyboard-first workflow

Recurring Tasks

Set tasks to automatically regenerate on a schedule:

• Frequencies: Daily, weekly, monthly, or yearly
• Weekly options: Select specific days of the week
• End conditions: Never, after N occurrences, or on a specific date
• Automatic creation: When a recurring task is marked done, the next occurrence is created
• Visual indicator: Recurring tasks show a ↻ badge in lists and kanban

Command Palette

• Cmd+P (or Ctrl+P) opens VS Code-style command palette
• Fuzzy search across all commands
• Context-aware actions (task commands only appear on task pages)
• Quick navigation to any ParaItem

Tags / Labels

Add colored tags to tasks, notes, files, and ParaItems for cross-cutting organization:

• 7 colors - Blue, green, yellow, red, purple, cyan, orange
• Theme-aware - Tags match your selected theme
• Autocomplete - Quick tag input with existing tag suggestions
• Create on-the-fly - Add new tags directly from the tag input
• Filter by tag - Tasks and Notes tabs support filtering by tag

Collaboration

Share your projects with other users:

• Share by email - Add collaborators using their exact email address
• Full access - Collaborators can create, edit, and delete tasks, notes, and files
• Visual distinction - Shared projects show a "Shared with you" badge in the list and sidebar
• Self-removal - Collaborators can leave projects at any time
• Owner controls - Only owners can add/remove collaborators
• Settings tab - Dedicated tab (Tab 3) for editing, collaborators, and sharing
• Attribution - All changes show who created or last modified each item

Public Sharing

Share read-only public links to individual tasks, notes, and files:

• UUID-based URLs - Secure, unguessable links (e.g., /share/abc123-def456)
• Optional expiration - Set an expiration date or share indefinitely
• Enable/disable - Temporarily disable links without deleting them
• Multiple links per item - Create different links for different audiences
• Clipboard copy - Link automatically copied when created, with manual copy button
• Security warning - Confirmation dialog before creating public links
• Shared Links management - View and manage all shares in the Settings tab
• Branded public pages - Clean, minimal pages with your theme preference
• Rate limiting - Protection against abuse (30 requests/minute)

Notifications

Stay informed about activity in shared projects:

• Bell icon - Unread notification count displayed in navbar
• Activity feed - See all notifications on the dedicated notifications page
• Per-project activity - Each ParaItem dashboard shows recent activity
• Real-time tracking - Notifications sent when collaborators create, update, or delete items
• Mark as read - Mark individual notifications or all at once

Time Tracking

Stopwatch-style time tracking accessible from the navbar:

• Navbar timer - Start/stop timer from anywhere with live elapsed time display
• Optional linking - Link time entries to a project and/or task
• Manual entry - Add entries with custom start/end times
• Reports - Daily bar chart, per-project pie chart, summary stats
• CSV export - Download time data for external analysis
• Dashboard integration - Time tracked card on each project dashboard
• Quick actions - Start timer from dashboard or command palette
• Full-text search - Find time entries via Cmd+K search

Bookmarks

Save and organize URLs alongside your notes and files:

• URL saving - Paste any URL, metadata (title, description, favicon) fetched automatically
• Rich text comments - Add notes to any bookmark with full formatting
• Explorer integration - Bookmarks appear alongside notes and files in folders
• Offline archiving - Archive pages with SingleFile, Readability, or video download (yt-dlp)
• Tags - Organize bookmarks with the same tag system as tasks and notes
• Public sharing - Share bookmarks via public links
• Search - Full-text search across URL, title, description, and comments

External Storage Sync

Automatically sync all content to S3-compatible storage:

• One-way sync - Para is the source of truth, content pushed to external storage
• Markdown format - All content exported as Markdown with YAML frontmatter
• Directory structure - Organized by PARA category (Projects/Areas/Resources/Archives/Trash)
• Real-time + periodic - Changes synced immediately via background jobs, plus hourly full sync
• S3-compatible - Works with AWS S3, Backblaze B2, Minio, DigitalOcean Spaces
• Encrypted credentials - Storage credentials encrypted at rest
• File attachments - Binary files synced alongside markdown
• Configurable - Set up in Preferences, with connection testing and manual sync trigger

In-App Documentation

Built-in documentation with search:

• Markdown-based - Documentation written in Markdown with YAML frontmatter
• FTS5 search - Full-text search across all documentation
• Multi-locale - Available in English, French, and Dutch with English fallback
• Syntax highlighting - Code examples with Rouge syntax highlighting
• Categorized - Docs grouped by category for easy browsing

Themes

Three carefully crafted themes:

• Tokyo Night - Default dark theme
• Light - Clean light theme
• Catppuccin Mocha - Alternative dark theme

Onboarding Tour

New users are guided through the app with an interactive tour:

• Auto-start: Tour begins automatically on first login
• 12 steps: Covers PARA method, navigation, tasks, notes, files, quick actions, collaboration, and keyboard shortcuts
• Theme-aware: Tour popover matches your selected theme
• Replay anytime: Click "Take a Tour" in the account menu
• Translated: Available in English, French, and Dutch

Global Search

Find anything across all your content with full-text search:

• Cmd+K (or Ctrl+K) to open search from anywhere
• Navbar search box with live dropdown results
• Full-text search using SQLite FTS5 (fast, no external dependencies)
• Search across tasks, notes, files, and ParaItems
• Comment search - Find tasks by their comment content
• Result highlighting - Matching text highlighted in results
• Type filtering - Filter results by content type (tasks, notes, files, projects)
• Project scoping - Limit search to a specific ParaItem
• Includes shared content - Search finds items in projects shared with you

REST API

Programmatic access to your data via a versioned REST API:

• API key authentication - Generate keys in Preferences, authenticate via X-Api-Key header
• Key management - Up to 5 keys per user, optional expiration, SHA-256 hashed storage
• ParaItems endpoint - GET /api/v1/para_items with category/trashed filters
• Pagination - Page-based with Link headers (RFC 8288), X-Total-Count, X-Page, X-Per-Page
• Includes shared items - API returns both owned and collaborated projects
• Rate limiting - 100 requests/minute per API key via Rack::Attack
• OpenAPI spec - Full spec at /api/v1/openapi.yml
• Swagger UI - Interactive docs at /api/v1/docs
• Documentation - In-app docs in English, French, and Dutch

CLI Client

A terminal client built with Go and Bubble Tea:

• Import directories - para import <dir> scans a local directory and uploads to Para
• Markdown to Notes - .md files become Notes (title = filename, content = file body)
• File uploads - Non-markdown files uploaded as Files with original names
• Recursive structure - Subdirectories become Explorer directories, preserving the full tree
• Merge mode - If a ParaItem with the same name exists, content is merged into it
• Duplicate handling - Same-name items get suffixed (e.g., "readme - 2")
• TUI browser - Interactive terminal UI to browse ParaItems and Explorer contents
• Keyboard navigation - j/k to navigate, Enter to drill in, Esc to go back, Tab to filter

Roadmap

Potential features under consideration for future development:

Priority	Feature	Description
High	Task Dependencies	Link tasks so one blocks another until completed. Auto-transition from blocked to todo when dependency completes.
High	Due Date Reminders	Email notifications for upcoming and overdue tasks. User-configurable reminder timing.
Medium	Templates	Create ParaItem templates with pre-defined tasks and notes for repeatable project types.
Medium	Activity Timeline	A chronological view of all actions across all projects (global activity feed).
Medium	Quick Theme Toggle	Dark/light mode toggle in navbar without navigating to preferences.
Low	WebDAV / SSH Sync	Additional sync providers beyond S3.

Getting Started

Requirements

• Ruby 3.3.8
• Node.js 23.11.0
• Yarn
• SQLite3
• Go 1.24+ (for CLI client)

Quick Start

# Install dependencies and setup database
bin/setup

# Start development server
bin/dev

The app will be available at http://localhost:7747.

CLI Client

# Build the CLI
cd cli && go build -o para .

# Configure (create ~/.config/para/para.yml)
mkdir -p ~/.config/para
echo "server: http://localhost:7747
api_key: para_YOUR_KEY_HERE" > ~/.config/para/para.yml

# Import a directory
./para import /path/to/directory --category project

# Launch TUI browser
./para

Create an Account

1. Navigate to the app
2. Click "Sign up" to create an account
3. Create your first ParaItem (Project, Area, or Resource)
4. Start adding tasks, notes, and files

Tech Stack

Category	Technology
Framework	Rails 8.1.3
Database	SQLite3
Frontend	Hotwire (Turbo + Stimulus)
CSS	Bulma (SCSS) with CSS custom properties for theming
JavaScript	Importmap (no bundler needed)
Authentication	Rails 8 built-in
File Uploads	ActiveStorage
Rich Text	ActionText
Testing	RSpec + Mutant
CLI Client	Go 1.24 + Bubble Tea
Deployment	Kamal (Docker)

AI-Driven Development

This project follows strict development rules to ensure AI-generated code meets production standards. See AGENTS.md for the complete guidelines.

Key Principles

1. Test-Driven Development (TDD)

   • Write failing tests first
   • Implement minimal code to pass
   • Refactor while keeping tests green

2. Mutation Testing

   • Every method must survive mutation testing
   • No living mutants allowed - tests must catch all code changes
   • This ensures tests actually verify behavior, not just coverage

3. Security First

   • Brakeman static analysis on every change
   • Dependency audits (bundler-audit, yarn audit)
   • Data isolation verified with tests (users can't access others' data)

4. Code Quality

   • RuboCop with Rails omakase style
   • Consistent patterns throughout codebase
   • No dead code (mutation testing catches it)

Running the CI Suite

# Run all checks locally
bin/ci

This runs:

1. RuboCop (code style)
2. Security audits (Brakeman, bundler-audit, yarn audit, importmap audit)
3. RSpec tests
4. Seed tests
5. Mutation testing (all critical classes)

Development

Running Tests

# Run all tests
bundle exec rspec

# Run specific file
bundle exec rspec spec/models/user_spec.rb

# Run specific test by line
bundle exec rspec spec/models/user_spec.rb:15

Mutation Testing

# Test a class
bin/mutant 'User'

# Test a specific method
bin/mutant 'User#authenticate'

# Test a controller
bin/mutant 'SessionsController'

Code Quality

# Run linter
bin/rubocop

# Auto-fix issues
bin/rubocop -a

Security Checks

# Static analysis
bin/brakeman --quiet --no-pager

# Gem vulnerabilities
bin/bundler-audit

# JS vulnerabilities
bin/importmap audit
yarn audit

Deployment

Configured for deployment with Kamal:

# Deploy to production
bundle exec kamal deploy

# View logs
bundle exec kamal logs

# Open remote console
bundle exec kamal console

# Open remote Rails console
bundle exec kamal app exec -i 'bin/rails console'

# Run database migrations manually (if needed)
bundle exec kamal app exec 'bin/rails db:migrate'

Project Structure

app/
├── controllers/        # Request handling
├── models/             # Business logic
├── services/           # Complex operations (MoveService, SearchService, Sync)
├── jobs/               # Background jobs (sync, recurring tasks, bookmarks)
├── helpers/            # View helpers
├── views/              # ERB templates
└── javascript/
    └── controllers/    # Stimulus controllers (~40)

cli/                    # Go TUI client
├── cmd/                # Cobra commands (root, import)
└── internal/
    ├── api/            # HTTP client for Para REST API
    ├── config/         # Config file + flag loading
    ├── importer/       # Directory scanning + upload logic
    └── tui/            # Bubble Tea TUI browser

docs/                   # In-app documentation (en/fr/nl)
spec/
├── models/             # Model specs
├── requests/           # Controller specs
├── services/           # Service specs
├── helpers/            # Helper specs
└── rails_helper.rb     # RSpec configuration

License

This project is proprietary software.