gridka: Instructions file for Claude Code

CLAUDE.md

Project Overview

Gridka is a native macOS CSV viewer built with Swift (AppKit) and DuckDB (C API). It handles very large files (100M+ rows) via virtual scrolling and SQL-backed data access. The UI is purely AppKit — no SwiftUI, no web views, no Electron.

Architecture Rules

• Single process. DuckDB is embedded via C API through a bridging header. No IPC, no separate backend.
• AppKit only. Use NSTableView (view-based, with data source delegate), NSView, NSViewController. Never use SwiftUI.
• Every user interaction is SQL. Sort, filter, search all mutate a ViewState struct which is translated to a SQL query by QueryCoordinator. No in-memory data manipulation in Swift.
• Serial query execution. All DuckDB calls go through a single serial DispatchQueue. DuckDB connections are not thread-safe. UI updates dispatch back to main.
• Page-based row cache. RowCache fetches pages of 500 rows. Max 20 pages cached. LRU eviction. Never load all rows into memory.

Key Domain Types

• FileSession — represents one opened file, owns the DuckDB connection and table
• ViewState — current sort, filters, search term, visible range. Immutable value type. Every change produces a new ViewState.
• QueryCoordinator — pure function: ViewState → SQL String. No side effects. Highly testable.
• RowCache — LRU cache of fetched row pages. Cache key is page index. Invalidated when ViewState changes filters/sort.
• DuckDBEngine — thin wrapper around DuckDB C API. Owns database and connection lifecycle.
• ColumnDescriptor — column name, DuckDB type, display type, index.
• ColumnFilter — column name, operator, value. Type-aware operators.

Code Conventions

• Swift 5.10+, target macOS 14.0+
• No third-party dependencies beyond DuckDB static library
• Use final class for all classes unless inheritance is explicitly needed
• Prefer value types (structs, enums) for model layer
• Error handling: define errors in GridkaError enum, throw from engine layer, handle in UI layer
• Use DispatchQueue for concurrency (not async/await — AppKit delegate patterns don't mix well)
• All SQL strings are parameterized or escaped via helper functions. Never interpolate user input directly.