Skip to content

CLAUDE.md

Latest commit

 

History

History
73 lines (61 loc) · 3.63 KB

CLAUDE.md

File metadata and controls

73 lines (61 loc) · 3.63 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

Code Formatting

  • Format Swift code: ./format.sh (uses swift-format with project configuration)
  • Configuration file: .swift-format (4-space indentation, 140 character line length)
  • Never let the views or view closures get too large. Extract large subviews into their own struct (which also may increase performance since SwiftUI can reuse those view objects)
  • Keep views as small as possible
    • The max amount of props should not exceed 4 except for special cases
  • Create new files for views
  • Use .map(\.name) instead of .map { $0.name }, i.e., if you want to map over a member use the key path function overload

Build and Run

  • Build/run the macOS app: Open SQL Browser.xcodeproj in Xcode
  • Target: SQL Browser (macOS application)
  • Never build yourself. Ask the user to build the project themselves a provide error messages.

Architecture Overview

Application Type

  • macOS SQLite Browser: Document-based app for viewing and managing SQLite database files
  • SwiftUI: Primary UI framework using WindowGroup and Commands
  • SQLite3: Direct SQLite C API integration for database operations
  • Document Architecture: Uses FileDocument protocol for SQLite file handling

Key Components

  • SQLBrowserApp: Main app entry point with WindowGroup and FileCommands
  • ContentView: Primary UI showing database status and file management
  • SQLiteDocument: FileDocument implementation for SQLite file read/write
  • FileCommands: Menu commands for creating/opening SQLite databases
  • Custom UTTypes: Extensions for .sqlite and .db file type handling

Core Functionality

  • Database Creation: Creates new SQLite databases using temporary files
  • Database Opening: File picker with SQLite validation using sqlite3_open_v2
  • File Management: Tracks recent database files and current database
  • Document Integration: Full macOS document handling with export/import

Swift Conventions

  • 4-space indentation (configured in .swift-format)
  • 140 character line length
  • File-scoped access level privacy enabled
  • Multiline collection trailing commas
  • Ordered imports enforced

Data Flow

  1. Menu Commands: FileCommands trigger NotificationCenter events
  2. Event Handling: ContentView responds to createNewSQLiteFile/openSQLiteFile notifications
  3. File Operations: SQLiteDocument handles FileDocument protocol requirements
  4. SQLite Validation: Direct C API calls to verify database integrity
  5. State Management: SwiftUI @State for UI updates and file tracking

Database Operations & Threading

  • Thread Safety: All database operations must be executed on the main thread
  • Transaction Handling: Avoid nested transactions - let DatabaseManager handle transaction management
  • SQL Quoting: Use double quotes (") for table and column identifiers, not backticks (`)
  • Schema Changes: For complex schema changes (column removal, etc.), use table recreation pattern:
    1. Backup existing data with SELECT
    2. DROP TABLE old table
    3. CREATE TABLE new table with updated schema
    4. INSERT compatible data back into new table

File Structure

  • SQLBrowserApp.swift: Main app entry point
  • ContentView.swift: Primary UI and database interaction logic
  • SQLiteDocument.swift: FileDocument implementation for SQLite files
  • FileCommands.swift: Menu command definitions
  • UTType+Extensions.swift: Custom file type definitions
  • Notification+Extensions.swift: Custom notification names
  • UpdateTableView.swift: Table schema modification interface