ReadKeep/documentation/claude.md

# CLAUDE.md - readeck iOS Project Documentation

## Project Overview

**readeck iOS** is a native iOS client for [readeck](https://readeck.org) bookmark management. The app provides a clean, native iOS interface for managing bookmarks with features like swipe actions, search, tagging, and reading progress tracking.

### Key Information
- **Platform:** iOS (iPhone + iPad)
- **Language:** Swift
- **UI Framework:** SwiftUI
- **Architecture:** MVVM + Clean Architecture (3-layer: UI/Domain/Data)
- **Database:** CoreData
- **Dependencies:** Swift Package Manager
- **License:** MIT

## Architecture Summary

The project follows Clean Architecture with custom dependency injection:

```
UI Layer (SwiftUI Views + ViewModels)
    ↓
Domain Layer (Use Cases + Repository Protocols + Models)  
    ↓
Data Layer (Repository Implementations + API + CoreData)
```

### Core Components
- **Custom DI:** Protocol-based factory pattern (no external frameworks)
- **MVVM Pattern:** ViewModels handle business logic, Views handle presentation
- **Use Cases:** Single-responsibility business logic encapsulation
- **Repository Pattern:** Data access abstraction with protocols

## Project Structure

```
readeck/
├── UI/                           # SwiftUI Views & ViewModels
│   ├── Bookmarks/               # Main bookmark list
│   ├── BookmarkDetail/          # Article reader
│   ├── AddBookmark/             # Create new bookmarks
│   ├── Search/                  # Search functionality
│   ├── Settings/                # App configuration
│   ├── Labels/                  # Tag management
│   ├── Menu/                    # Navigation & tabs
│   ├── SpeechPlayer/            # Text-to-speech
│   └── Components/              # Reusable UI components
├── Domain/
│   ├── Model/                   # Core business models
│   ├── UseCase/                 # Business logic
│   ├── Protocols/               # Repository interfaces
│   └── Error/                   # Custom error types
├── Data/
│   ├── API/                     # Network layer & DTOs
│   ├── Repository/              # Data access implementations
│   ├── CoreData/                # Local database
│   └── Utils/                   # Helper utilities
└── Localizations/               # i18n strings
    ├── Base.lproj/
    ├── en.lproj/
    └── de.lproj/
```

## Key Features

### Implemented Features
- ✅ Browse bookmarks (All, Unread, Favorites, Archive by type)
- ✅ Share Extension for adding URLs from Safari/other apps
- ✅ Swipe actions for quick bookmark management
- ✅ Native iOS design with Dark Mode support
- ✅ Full iPad Support with Multi-Column Split View
- ✅ Font customization in reader
- ✅ Article view with reading time and word count
- ✅ Search functionality
- ✅ Tag/label management
- ✅ Reading progress tracking
- ✅ Offline support with auto-sync when reconnected
- ✅ Text-to-speech (Read Aloud feature)

### Planned Features (v1.1.0)
- ⏳ Bookmark filtering and sorting options
- ⏳ Collection management
- ⏳ Custom themes
- ⏳ Text highlighting in articles
- ⏳ Multiple selection for bulk actions

## Development Setup

### Requirements
- Xcode 15.0+
- iOS 17.0+ deployment target
- Swift Package Manager (dependencies auto-resolved)

### Key Dependencies
- **netfox:** Network debugging (debug builds only)
- **RswiftLibrary:** Resource management

### Build Configurations
- **Debug:** Includes netfox for network debugging
- **Release:** Production-ready build
- **URLShare Extension:** Share extension target

## Localization (Weblate Integration)

### Current Setup
The project has been converted from Apple's String Catalog (.xcstrings) to traditional .strings format for Weblate compatibility:

```
readeck/Localizations/
├── Base.lproj/Localizable.strings    # Source language (English)
├── en.lproj/Localizable.strings      # English localization
└── de.lproj/Localizable.strings      # German localization
```

### Weblate Configuration
When setting up Weblate:
- **File mask:** `readeck/Localizations/*.lproj/Localizable.strings`
- **Monolingual base:** `readeck/Localizations/Base.lproj/Localizable.strings`  
- **File format:** "iOS Strings (UTF-8)"
- **Repository:** Connect to main Git repository

### Adding New Languages
1. Create new `.lproj` directory (e.g., `fr.lproj/`)
2. Copy `Base.lproj/Localizable.strings` to new directory
3. Weblate will automatically detect and manage translations

## App State Management & Navigation

### Setup Flow & Authentication
The app uses a sophisticated setup and authentication system:

**Initial Setup Detection:**
- `AppViewModel.hasFinishedSetup` controls the main app flow
- `readeckApp.swift:19` determines whether to show setup or main app
- Setup status is persisted via `SettingsRepository.hasFinishedSetup`

**Authentication & Keychain Management:**
- `KeychainHelper` (singleton) securely stores sensitive credentials:
  - Server endpoint (`readeck_endpoint`)
  - Username (`readeck_username`) 
  - Password (`readeck_password`)
  - Authentication token (`readeck_token`)
- Access Group: `8J69P655GN.de.ilyashallak.readeck` for app group sharing
- Automatic logout on 401 responses via `AppViewModel.handleUnauthorizedResponse()`

**Device-Specific Navigation:**
The app automatically adapts its navigation structure based on device type:

```swift
// MainTabView.swift determines layout
if UIDevice.isPhone {
    PhoneTabView()           // Tab-based navigation
} else {
    PadSidebarView()         // Sidebar + split view navigation
}
```

**Navigation Patterns:**
- **iPhone:** `PhoneTabView` - Traditional tab bar with "More" tab for additional features
- **iPad:** `PadSidebarView` - NavigationSplitView with sidebar, content, and detail panes
- Both share the same underlying ViewModels and business logic

**Key Navigation Components:**
- `SidebarTab` enum defines all available sections
- Main tabs: `.all`, `.unread`, `.favorite`, `.archived`
- More tabs: `.search`, `.article`, `.videos`, `.pictures`, `.tags`, `.settings`
- Consistent routing through `tabView(for:)` methods in both variants

## Key Architectural Decisions

### 1. Custom Dependency Injection
- **Why:** Avoid external framework dependencies, full control
- **How:** Protocol-based factory pattern in `DefaultUseCaseFactory`
- **Benefit:** Easy testing with mock implementations

### 2. Repository Pattern
- **Domain Layer:** Defines protocols (e.g., `PBookmarksRepository`)
- **Data Layer:** Implements protocols (e.g., `BookmarksRepository`)
- **Benefit:** Clean separation between business logic and data access

### 3. Use Cases
- Single-responsibility classes for each business operation
- Examples: `CreateBookmarkUseCase`, `GetBookmarksUseCase`
- **Benefit:** Testable, reusable business logic

### 4. SwiftUI + MVVM
- ViewModels as `@ObservableObject` classes
- Views are pure presentation layer
- State management through ViewModels

## Testing Strategy

### Current Test Coverage
- **Unit Tests:** `readeckTests/` (basic coverage)
- **UI Tests:** `readeckUITests/` (smoke tests)

### Testing Philosophy
- Protocol-based DI enables easy mocking
- Use Cases can be tested in isolation
- Repository implementations tested with real/mock data sources

## Distribution

### TestFlight Beta
- Public beta available via TestFlight
- Link: `https://testflight.apple.com/join/cV55mKsR`
- Regular updates with new features

### Release Process
- Uses fastlane for build automation
- Automated screenshot generation
- Version management in Xcode project

## API Integration

### readeck Server API
- RESTful API communication
- DTOs in `Data/API/DTOs/`
- Authentication via username/password
- Token management with automatic refresh
- Support for local network addresses (development)

### Key API Operations
- User authentication
- Bookmark CRUD operations
- Tag/label management
- Article content fetching
- Progress tracking

## Offline Support

### Local Storage
- CoreData for offline bookmark storage
- Automatic sync when connection restored
- Queue system for offline operations
- Conflict resolution strategies

### Sync Strategy
- Background sync when app becomes active
- User-initiated sync option
- Visual indicators for sync status

## Performance Considerations

### Memory Management
- Lazy loading of bookmark content
- Image caching for article thumbnails
- Proper SwiftUI view lifecycle management

### Network Optimization
- Background download of article content
- Request batching where possible
- Retry logic for failed requests

## Contributing Guidelines

### Code Style
- Follow Swift API Design Guidelines
- Use SwiftUI best practices
- Maintain separation of concerns between layers

### New Feature Development
1. Define domain models in `Domain/Model/`
2. Create use case in `Domain/UseCase/`
3. Implement repository in `Data/Repository/`
4. Create ViewModel in appropriate UI folder
5. Build SwiftUI view
6. Update factory for DI wiring

### Git Workflow
- Main branch: `main`
- Development branch: `develop`
- Feature branches: `feature/feature-name`
- Commit format: `feat:`, `fix:`, `docs:`, etc.

## Troubleshooting

### Common Issues
1. **Build Errors:** Ensure Xcode 15.0+ and clean build folder
2. **Network Issues:** Check server URL and credentials
3. **CoreData Migrations:** May need to reset data during development
4. **Localization:** Ensure .strings files are properly formatted

### Development Tips
- Use netfox in debug builds to monitor API calls
- Check logging configuration in debug settings
- Test both iPhone and iPad layouts
- Verify share extension functionality

## Security Considerations

### Data Protection
- Keychain storage for user credentials
- No sensitive data in UserDefaults
- Secure network communication (HTTPS enforced for external domains)

### Privacy
- No analytics or tracking libraries
- Local data storage only
- User controls all data sync

---

*This documentation is maintained alongside the codebase. Update this file when making architectural changes or adding new features.*