CLAUDE.md

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

Project Overview

This is a macOS invoicing application built with SwiftUI and SwiftData called "Facturation" (French for "Billing"). The app helps manage clients, invoices, products, and business information for a company named ExoTROPIC.

Build & Development Commands

Building the Project

• Build: ⌘ + B in Xcode
• Run: ⌘ + R in Xcode
• Clean: ⌘ + Shift + K in Xcode

Requirements

• macOS 14.0+ (Sonoma)
• Xcode 15.0+
• Swift 5.9+

No Package Manager

This project uses native Apple frameworks only - no external dependencies or package managers.

Architecture

Core Pattern

• Architecture: MVVM with SwiftData persistence
• UI Framework: SwiftUI for macOS
• Data Layer: SwiftData (Apple's successor to Core Data)
• Main Service: DataService (singleton) handles all CRUD operations

Key Components

┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Models          │ │ Services        │ │ Views           │
│ (SwiftData)     │─│ DataService     │─│ SwiftUI         │
└─────────────────┘ └─────────────────┘ └─────────────────┘

Data Models

Core Models (Models/)

• Facture: Invoice entity with status tracking, VAT calculations, and line items
• LigneFacture: Invoice line items with quantity, unit price, and product references
• Client: Customer entity with contact info and address details
• Entreprise: Company settings and invoice numbering configuration
• Produit: Product catalog with pricing and descriptions
• Statistiques: Statistics and analytics data model

Model Relationships

• Facture ↔ Client (many-to-one)
• Facture ↔ LigneFacture (one-to-many, cascade delete)
• LigneFacture ↔ Produit (many-to-one, optional)

Important Enums

• StatutFacture: Invoice status (brouillon, envoyee, payee, EnRetard, annulee)
• ConditionsPaiement: Payment methods (virement, cheque, espece, carte)

ViewModels (ViewModels/)

• EditableFacture: Editable wrapper for invoice editing
• EditableLigneFacture: Editable wrapper for invoice line items

Data Service (Services/DataService.swift)

Key Features

• Singleton Pattern: DataService.shared
• Published Properties: @Published var clients, factures, produits
• Async/Await: All CRUD operations are async
• Resilient Init: Handles SwiftData container failures with fallback to in-memory storage

Common Operations

// Fetching data
await dataService.fetchClients()
await dataService.fetchFactures()

// CRUD operations
await dataService.addClient(client)
await dataService.updateFacture(facture)
await dataService.deleteClient(client)

// Utilities
let stats = dataService.getStatistiques()
let numero = await dataService.genererNumeroFacture()

View Structure

Main Views (Views/)

• Dashboard: Overview with statistics and recent activity (DashboardView/)
• Clients: Client management (list, add, edit, delete) (Client/)
• Factures: Invoice management with status filtering (FacturesView/)
• Parametres: Company settings and configuration (Parametres/)
• Produits: Product catalog management (Produits/)
• Stats: Charts and analytics (Stats/)
• Developer: Developer tools and debugging (Developer/)

Navigation

• Modern sidebar-based navigation with ModernContentView as root
• Tab-based structure with enum NavigationTab

Shared Components (Shared/)

• Components/: Reusable UI components (AppButton, AppCard, AppTextField, WindowManager)
• Extensions/: Utility extensions for common tasks

PDF Generation

The app includes comprehensive PDF generation capabilities using:

• Core Graphics: For custom PDF layouts
• PDFKit: For PDF handling and display
• PDFService: Handles PDF creation and formatting with advanced layout
• PageLayoutCalculator: Calculates optimal page layouts for invoices
• InvoicePageContent: Structures invoice content for PDF generation
• ClientFacturesPDFView: SwiftUI view for client-specific PDF generation

Extensions & Utilities

Extensions (Extensions/)

• MacOSColors.swift: macOS-specific color adaptations
• Extensions.swift: Double, Date, String formatting utilities
• Client+Extensions.swift: Client-specific computed properties and methods

Key Utilities

• Euro currency formatting
• French date formatting
• Email/SIRET validation
• Address formatting helpers

Testing

Test Structure

• FacturationTests/: Contains unit tests
• ImportPDFTests.swift: PDF import functionality tests

Running Tests

• Use ⌘ + U in Xcode to run all tests
• Individual test methods can be run via Xcode test navigator
• Test Target: FacturationTests with PDF import testing capabilities

Testing Infrastructure

• Tests use in-memory SwiftData containers for isolation
• PDF and Excel import functionality is thoroughly tested
• XCTest framework with Vision and PDFKit testing support

Import/Export Features

Supported Formats

• Excel Import: ExcelImporter.swift with CoreXLSX dependency for importing client and invoice data
• PDF Import: PDFImporter.swift for extracting invoice data from PDF documents using Vision framework
• JSON Export: Built-in export functionality for clients and invoices

Additional Services

• StatistiquesService: Handles statistics calculations and data aggregation
• DataService: Centralized data management with async/await patterns

Special Considerations

SwiftData Gotchas

• Always insert entities into ModelContext before establishing relationships
• Use @Relationship(inverse:) for bidirectional relationships
• Handle container initialization failures gracefully
• Resilient initialization: DataService implements fallback to in-memory storage if persistent storage fails
• Migration handling: Automatic schema migration with error recovery

macOS Specifics

• Window minimum size: 1200x800
• Uses native macOS UI patterns and colors
• Supports keyboard shortcuts and menu commands

French Localization

• UI is primarily in French
• Handles French business requirements (SIRET, TVA, etc.)
• Uses European number formatting
• Company name: ExoTROPIC (default business entity)

Development Notes

Code Style

• Swift naming conventions throughout
• Extensive use of computed properties for derived values
• Async/await pattern for all data operations
• SwiftUI view composition with clear separation of concerns

Error Handling

• Comprehensive error handling in DataService
• Fallback mechanisms for data persistence failures
• User-friendly error messages in French

Current Project Status

Key Features Implemented

• Complete CRUD operations for clients, invoices, and products
• Modern SwiftUI interface with macOS-specific adaptations
• Advanced PDF generation with custom layouts
• Excel/PDF import capabilities with Vision framework
• Comprehensive statistics and analytics
• Robust data persistence with SwiftData
• French business compliance (SIRET, TVA validation)

External Dependencies

• CoreXLSX: For Excel file import functionality
• Vision: For PDF text extraction and processing
• PDFKit: For PDF document handling

Asset Management

• Extensive sunset image collection (37 images in ViewModels/Assets.xcassets/Sunsets/)
• Complete app icon set with multiple resolutions
• Organized asset catalogs for maintainability

This codebase represents a complete, production-ready macOS invoicing application with robust data management, PDF generation, and import/export capabilities.