BudgetApp/CLAUDE.md

CLAUDE.md

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

Development Commands

Build and Run

• flutter run - Run the app in debug mode
• flutter build apk - Build APK for Android
• flutter build ios - Build for iOS

Code Generation

• flutter packages pub run build_runner build - Generate Hive adapters and other generated code
• flutter packages pub run build_runner build --delete-conflicting-outputs - Clean build with conflict resolution

Testing and Quality

• flutter test - Run all tests
• flutter analyze - Run static analysis using flutter_lints
• flutter pub get - Install dependencies
• flutter pub upgrade - Upgrade dependencies

Localization

• flutter gen-l10n - Generate localization files (configured in l10n.yaml)

Architecture Overview

This is a Flutter budget tracking application with SMS transaction parsing capabilities. The app follows Clean Architecture principles with BLoC pattern for state management.

Key Architectural Components

Dependency Injection: Uses GetIt for dependency injection with a two-stage initialization:

• Global dependencies (user management, auth) initialized at startup
• User-specific dependencies (transactions, categories, etc.) initialized after authentication

Database: Hive (local NoSQL database) for data persistence with code generation for type adapters

State Management: BLoC pattern with flutter_bloc:

• Blocs for complex state (AuthBloc, TransactionBloc)
• Cubits for simpler state (UserCubit, CategoryCubit, TagCubit, SettingsCubit, SmsCubit)

SMS Integration: Uses another_telephony package to read SMS messages and automatically parse bank transaction notifications

Project Structure

lib/
├── data/
│   ├── database/           # Hive database service
│   └── repositories/       # Data access layer with interfaces
├── hive/                   # Hive type adapters (generated)
├── logic/                  # BLoC/Cubit state management
├── models/                 # Data models with Hive adapters
├── pages/                  # UI screens and widgets
├── services/               # Business logic services
├── theme/                  # App theming
├── utils/                  # Utility functions
├── l10n/                   # Localization files
├── main.dart               # App entry point
└── injection_container.dart # Dependency injection setup

Key Models

• User - User authentication and profile
• TransactionRecord - Financial transactions
• Category - Transaction categories with icons/colors
• Tag - Transaction tags
• SmsMessage - SMS messages for transaction parsing
• AppSettings - User preferences (theme, language)

Authentication Flow

1. App starts with AuthBloc checking existing user
2. If no user, shows LoginPage
3. After login, calls initUserSpecificDependencies() to set up user data
4. User data is scoped and isolated per user via Hive boxes

SMS Transaction Processing

The app can automatically parse SMS messages from banks to create transactions:

• Monitors incoming SMS via another_telephony
• Parses transaction details using configurable patterns
• Creates transactions automatically with suggested categories

Localization

• Supports Russian (ru) and English (en)
• Uses flutter_localizations with ARB files
• Configured in l10n.yaml

Coding Style Guidelines

Naming Conventions

• Interface names should be prefixed with I (e.g., IUserService, ITransactionRepository)
• Private class members should be prefixed with an underscore (_)
• Follow dart naming conventions: camelCase for variables/methods, PascalCase for classes

Flutter-Specific Best Practices

• Prefer composition and small components: Break down UI into small, reusable components rather than writing large monolithic widgets
• Design for good user experience: Provide clear, minimal, and non-blocking UI states
• Use lightweight placeholders: When data is loading, show skeleton screens rather than heavy loading indicators
• Optimize for Flutter Compiler: Write code that enables automatic optimizations and reduces unnecessary re-renders

BLoC/Cubit Architecture

• Use Blocs for complex state management with events (AuthBloc, TransactionBloc)
• Use Cubits for simpler state management (UserCubit, CategoryCubit, TagCubit, SettingsCubit, SmsCubit)
• Follow the established pattern in the logic/ directory
• Ensure proper separation of concerns between UI and business logic

Performance Considerations

• Create small, focused widgets that can be efficiently rebuilt
• Implement proper shouldRebuild logic in BlocBuilder/BlocListener
• Avoid heavy operations in build methods

Important Notes

• The project uses Russian comments and some Russian text in UI
• SMS functionality requires Android permissions for reading SMS
• Hive boxes are user-scoped for data isolation
• The default test is outdated and needs updating for the actual app structure
• Build runner is required for Hive adapter generation after model changes