Architecture

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/fulsomenko/kanban/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

​

Tech Stack

​

Workspace Structure

crates/
├── kanban-core/        # Core traits, errors, and result types
├── kanban-domain/      # Domain models (Board, Card, Column, Tag)
├── kanban-persistence/ # JSON storage, versioning & migrations
├── kanban-tui/         # Terminal UI with ratatui
├── kanban-cli/         # CLI entry point
└── kanban-mcp/         # Model Context Protocol server

​

Dependency Flow

​

Crate Descriptions

​

kanban-core

• KanbanError - Centralized error types using thiserror
• KanbanResult<T> - Standard result type alias
• Graph<N, E> - Generic graph data structure for dependencies
• InputState - Text input handling
• AppConfig - Application configuration
• SelectionState - UI selection management
• Editable - Trait for editable entities

• Error handling with thiserror
• Async traits with async-trait
• Type-safe graph operations

// Example: Core error handling
pub type KanbanResult<T> = Result<T, KanbanError>;

#[derive(Debug, thiserror::Error)]
pub enum KanbanError {
    #[error("IO error: {0}")]
    Io(#[from] std::io::Error),
    // ... more variants
}

​

kanban-domain

• Board - Top-level kanban board with columns and metadata
• Column - Board columns with WIP limits and ordering
• Card - Task cards with priority, status, due dates, story points
• Tag - Categorization tags
• Sprint - Sprint planning and tracking
• ArchivedCard - Historical card data

• Rich domain models with behavior methods
• Command pattern for state mutations
• Card dependency graph with blocking relationships
• Search and filtering capabilities
• Export/import functionality
• History management for undo/redo

// Example: Domain model with behavior
pub struct Card {
    pub id: CardId,
    pub column_id: ColumnId,
    pub title: String,
    pub priority: CardPriority,
    pub status: CardStatus,
    pub story_points: Option<u8>,
    pub due_date: Option<NaiveDate>,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
}

impl Card {
    pub fn update_status(&mut self, status: CardStatus) {
        self.status = status;
        self.updated_at = Utc::now();
    }
}

​

kanban-persistence

• Progressive Auto-Save: Changes saved immediately after each operation
• Async Processing: Commands queued via bounded channel, processed by background worker
• Conflict Detection: Multi-instance changes detected via file metadata
• Format Versioning: Automatic V1→V2 migration with backup creation
• Atomic Writes: Crash-safe pattern (temp file → atomic rename)
• Own-Write Detection: Metadata-based filtering prevents false positives

• notify for file watching
• tempfile for atomic writes
• serde_json for serialization

​

kanban-tui

• app - Application state and main event loop
• ui - Rendering components using ratatui widgets
• events - Keyboard and terminal event handling
• input - Input state management
• dialog - Dialog interaction patterns
• editor - External editor integration

• Vim-like keyboard navigation (hjkl)
• Multiple view modes (board, list, task list)
• Context-aware shortcuts
• Modal dialogs for input
• External editor support
• Clipboard integration with arboard
• Markdown rendering with pulldown-cmark

​

kanban-cli

• Command parsing with clap
• Subcommand handlers (board, card, column, sprint, export)
• Tracing/logging initialization
• TUI coordination
• Shell completion generation

kanban                    # Launch TUI
kanban board list         # List boards
kanban card create        # Create card
kanban export             # Export data

​

kanban-mcp

• Full read/write access to boards, cards, columns, sprints
• JSON-RPC over stdio using rmcp SDK
• Resource and tool endpoints
• Schema validation with schemars

​

SOLID Principles

​

Design Patterns

​

Command Pattern

pub trait Command {
    fn execute(&mut self, ctx: &mut CommandContext) -> KanbanResult<()>;
    fn description(&self) -> String;
}

// Example: Create card command
pub struct CreateCard {
    pub board_id: BoardId,
    pub column_id: ColumnId,
    pub title: String,
    pub priority: CardPriority,
}

impl Command for CreateCard {
    fn execute(&mut self, ctx: &mut CommandContext) -> KanbanResult<()> {
        let card = Card::new(
            self.column_id,
            self.title.clone(),
            /* ... */
        );
        ctx.cards.push(card);
        Ok(())
    }
}

1. Event Handler (TUI): Processes keyboard input
2. Command: Encapsulates the mutation
3. StateManager: Executes command via CommandContext
4. Dirty Flag: Marks state as dirty
5. Progressive Save: Auto-saves via async channel

​

Repository Pattern

// Async file operations
pub struct FileRepository {
    path: PathBuf,
}

impl FileRepository {
    pub async fn save(&self, data: &AllBoardsExport) -> KanbanResult<()> {
        // Atomic write: temp file → rename
    }

    pub async fn load(&self) -> KanbanResult<AllBoardsExport> {
        // Load and migrate versions
    }
}

​

Observer Pattern

use notify::{Watcher, RecursiveMode};

let (tx, rx) = channel();
let mut watcher = notify::watcher(tx, Duration::from_secs(1))?;
watcher.watch(&data_file, RecursiveMode::NonRecursive)?;

// React to external changes
while let Ok(event) = rx.recv() {
    handle_file_change(event);
}

​

Inspirations from lazygit

​

Type Safety

// Newtype pattern for IDs
pub struct BoardId(Uuid);
pub struct CardId(Uuid);
pub struct ColumnId(Uuid);

// Enums for state machines
pub enum CardStatus {
    Todo,
    InProgress,
    Done,
}

pub enum CardPriority {
    Low,
    Medium,
    High,
    Critical,
}

// Type-safe builders
let card = Card::new(column_id, "Task".to_string(), 0)
    .with_priority(CardPriority::High)
    .with_story_points(5);

​

Error Handling Strategy

#[derive(Debug, thiserror::Error)]
pub enum KanbanError {
    #[error("Card not found: {0}")]
    CardNotFound(CardId),
}

fn main() -> anyhow::Result<()> {
    // Application logic
}

​

Performance Considerations

• Minimal Allocations: Use &str over String where possible
• Async I/O: Tokio for non-blocking file operations
• Efficient Rendering: Only redraw changed UI components
• Lazy Loading: Load boards on-demand
• Release Profile: LTO, single codegen unit, strip symbols

[profile.release]
opt-level = 3
lto = true
codegen-units = 1
strip = true

​

Next Steps