Skip to content

CLAUDE.md

Latest commit

 

History

History
87 lines (66 loc) · 4.17 KB

CLAUDE.md

File metadata and controls

87 lines (66 loc) · 4.17 KB

CLAUDE.md

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

Project Overview

TypoFixer is a macOS desktop application that uses AI (Google Gemini or OpenAI) to correct Czech language text for grammar, spelling, and style. Users paste text, click "Fix", and receive corrected output.

Build & Test Commands

# Build (Debug)
xcodebuild -project TypoFixer.xcodeproj -scheme TypoFixer -configuration Debug build

# Build (Release)
xcodebuild -project TypoFixer.xcodeproj -scheme TypoFixer -configuration Release build

# Run Tests
xcodebuild -project TypoFixer.xcodeproj -scheme TypoFixer test

No package manager is used. The project has zero external dependencies—only native Apple frameworks.

Architecture

Layered SwiftUI structure:

  • Presentation: ContentView.swift, SettingsView.swift, Views/*.swift (reusable components)
  • ViewModel: ContentViewModel.swift (@Observable, coordinates state and AI service)
  • Services: Services/AIService.swift (actor-based API orchestration)
  • Business Logic: AIRequestBuilder.swift (request construction, response parsing), TextProcessor.swift (response cleaning)
  • Configuration: AIProviderConfig.swift (provider selection in UserDefaults)
  • Security: KeychainHelper.swift (API key storage in macOS Keychain)
  • Protocols: Protocols/*.swift (KeychainProviding, AIConfigProviding for testability)
  • Environment: Environment/EnvironmentKeys.swift (SwiftUI dependency injection)

Key patterns:

  • Singletons for shared state: AIProviderConfig.shared, KeychainHelper.shared
  • Actor pattern for thread-safe AIService
  • @Observable for reactive ContentViewModel
  • Protocol-based dependency injection for testability
  • SwiftUI environment keys for dependency distribution
  • NotificationCenter for cross-component communication (apiKeyDidChange, providerDidChange)
  • NSViewRepresentable bridges for custom keyboard handling (Cmd+Return to fix, Escape to switch focus)

API Integration:

  • Gemini: API key in URL query param, response at candidates[0].content.parts[0].text
  • OpenAI: API key in Authorization Bearer header, response at choices[0].message.content
  • Providers: gemini-flash-lite (default), gemini-flash, openai-gpt4, openai-gpt35

Key Files

App & Views:

  • TypoFixerApp.swift - App entry point with main Window and Settings scenes
  • ContentView.swift - Main UI with input/output editors and fix button
  • SettingsView.swift - Provider selection and API key management
  • Views/FixButton.swift - Branded button with loading state and Cmd+Return support
  • Views/InputTextEditor.swift - NSViewRepresentable with Cmd+Return detection
  • Views/OutputTextEditor.swift - NSViewRepresentable with Escape key handling

Logic & Services:

  • ContentViewModel.swift - @Observable view model managing state and AI service
  • Services/AIService.swift - Actor handling API requests with dependency injection
  • AIRequestBuilder.swift - Builds requests and parses responses for both providers
  • TextProcessor.swift - Cleans API responses (removes unwanted wrapping quotes)

Configuration & Security:

  • AIProviderConfig.swift - Manages provider selection (4 providers)
  • KeychainHelper.swift - Secure API key storage in macOS Keychain
  • TypoFixer.entitlements - App Sandbox with keychain and network access

Protocols & Environment:

  • Protocols/KeychainProviding.swift - Protocol for keychain operations
  • Protocols/AIConfigProviding.swift - Protocol for AI configuration
  • Environment/EnvironmentKeys.swift - SwiftUI environment keys for DI

Testing

Test Files:

  • TypoFixerTests/AIRequestBuilderTests.swift - Request building and response parsing (11 tests)
  • TypoFixerTests/AIServiceTests.swift - API key retrieval and provider selection (3 tests)
  • TypoFixerTests/TextProcessorTests.swift - Quote handling logic (8 tests)

Mocks:

  • TypoFixerTests/Mocks/MockKeychain.swift - In-memory keychain with call counting
  • TypoFixerTests/Mocks/MockAIConfig.swift - Configurable provider mock

Testing patterns: XCTest framework, async/await tests, error case testing with XCTAssertThrowsError, protocol-based mocking