# CLAUDE.md

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

## Project Overview

Portfolio Journal is a native iOS investment portfolio tracker built with Swift and SwiftUI. It helps users track investments, monitor performance with charts and predictions, set financial goals, and maintain an investment journal.

**Target:** iOS 17.6+ (widget supports iOS 16.0+)

## Build Commands

```bash
# Open project in Xcode
open PortfolioJournal.xcodeproj

# Build for Debug
xcodebuild -scheme PortfolioJournal -configuration Debug build

# Build for Release
xcodebuild -scheme PortfolioJournal -configuration Release build

# Run on simulator
xcodebuild -scheme PortfolioJournal -configuration Debug -destination 'platform=iOS Simulator,name=iPhone 15' build

# Clean build
xcodebuild -scheme PortfolioJournal clean
```

## Architecture

The app uses Clean Architecture with MVVM pattern:

```
PortfolioJournal/
├── App/                    # Entry point: PortfolioJournalApp.swift, AppDelegate, ContentView
├── Models/CoreData/        # Core Data entities and CoreDataStack singleton
├── Repositories/           # Data access layer with @MainActor CRUD operations
├── Services/               # Business logic (CalculationService, PredictionEngine, IAPService, etc.)
├── ViewModels/             # MVVM view models for each feature
├── Views/                  # SwiftUI views organized by feature
│   ├── Dashboard/          # Main dashboard with evolution charts
│   ├── Charts/             # Financial visualizations (allocation, performance, drawdown)
│   ├── Sources/            # Investment source management
│   ├── Goals/              # Goal tracking and progress
│   ├── Journal/            # Journal entries
│   ├── Settings/           # App settings and import/export
│   ├── Security/           # Face ID/PIN lock (AppLockView)
│   └── Components/         # Shared UI components
├── Utilities/              # Helpers: KeychainService, FreemiumValidator, formatters, extensions
└── Resources/              # Info.plist, GoogleService-Info.plist, assets

PortfolioJournalWidget/     # iOS Home Screen Widget (WidgetKit)
```

### Core Data Model

Key entities: `Account`, `InvestmentSource`, `Snapshot`, `Category`, `Goal`, `Asset`, `Transaction`, `AppSettings`, `PremiumStatus`

Data flows through `CoreDataStack` singleton which manages CloudKit sync and AppGroup shared container for widget access.

### Key Services

- **CalculationService**: Portfolio metrics, returns calculation, allocation analysis
- **PredictionEngine**: Investment forecasting algorithms with caching
- **IAPService**: StoreKit 2 in-app purchases
- **AdMobService**: Google Mobile Ads integration
- **ImportService/ExportService**: CSV data import/export
- **AppLockService**: Biometric/PIN security via Keychain

## Dependencies

Managed via Swift Package Manager:
- Firebase iOS SDK (v12.7.0+) - Analytics
- Google Mobile Ads SDK

Native frameworks: SwiftUI, Combine, CoreData, CloudKit, WidgetKit, StoreKit 2, LocalAuthentication

## App Initialization Flow

```
PortfolioJournalApp (@main)
  └── AppDelegate (Firebase, AdMob, Notifications init)
  └── ContentView
      ├── OnboardingView (first launch)
      ├── AppLockView (if security enabled)
      └── TabBar: Dashboard | Sources | Goals | Journal | Settings
```

## Localization

Supported languages: English (`en.lproj`), Spanish (`es-ES.lproj`)

## Development Notes

- Use `SampleDataService` to generate demo data for testing
- Premium features are gated via `FreemiumValidator`
- Widget shares data through AppGroup container
- Sensitive data stored in Keychain via `KeychainService`